/ Hex Artifact Content
Login

Artifact e6ead287be496055ade50424b7799f84475da7d7:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
90c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
90d0: 71 6c 69 74 65 33 5f 73 68 6d 20 73 71 6c 69 74  qlite3_shm sqlit
90e0: 65 33 5f 73 68 6d 3b 0a 73 74 72 75 63 74 20 73  e3_shm;.struct s
90f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
9100: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
9110: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
9120: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
9130: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32  ber (currently 2
9140: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
9150: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
9160: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
9170: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
9180: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
9190: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
91a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
91b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
91c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
91d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
91e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
91f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
9200: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9210: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9220: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9230: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9240: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
9250: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
9260: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
9270: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
9280: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
9290: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
92a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
92b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
92c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
92d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
92e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
92f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
9300: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9310: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9320: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9330: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9340: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9350: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9360: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
9370: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
9380: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
9390: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
93a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
93b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
93c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
93d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
93e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
93f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
9400: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9410: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9420: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9430: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9440: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
9450: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
9460: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
9470: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
9480: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
9490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
94a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
94b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
94e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
94f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9500: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9520: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9530: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9540: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9550: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9560: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9570: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
9580: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9590: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
95a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
95b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
95c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
95d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
95e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
95f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
9600: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
9610: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
9620: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9630: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
9640: 68 6d 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  hm**);.  int (*x
9650: 53 68 6d 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ShmSize)(sqlite3
9660: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 73  _vfs*, sqlite3_s
9670: 68 6d 2a 2c 20 69 6e 74 20 72 65 71 53 69 7a 65  hm*, int reqSize
9680: 2c 20 69 6e 74 20 2a 70 4e 65 77 53 69 7a 65 29  , int *pNewSize)
9690: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 47 65  ;.  int (*xShmGe
96a0: 74 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  t)(sqlite3_vfs*,
96b0: 20 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c 20 69   sqlite3_shm*, i
96c0: 6e 74 20 72 65 71 53 69 7a 65 2c 20 69 6e 74 20  nt reqSize, int 
96d0: 2a 70 53 69 7a 65 2c 20 76 6f 69 64 2a 2a 29 3b  *pSize, void**);
96e0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 52 65 6c  .  int (*xShmRel
96f0: 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  ease)(sqlite3_vf
9700: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 73 68 6d 2a  s*, sqlite3_shm*
9710: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
9720: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ock)(sqlite3_vfs
9730: 2a 2c 20 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c  *, sqlite3_shm*,
9740: 20 69 6e 74 20 64 65 73 69 72 65 64 4c 6f 63 6b   int desiredLock
9750: 2c 20 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 29 3b  , int *gotLock);
9760: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c 6f  .  int (*xShmClo
9770: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
9780: 2c 20 73 71 6c 69 74 65 33 5f 73 68 6d 2a 2c 20  , sqlite3_shm*, 
9790: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
97a0: 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
97b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
97c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 6c 64  const char *zOld
97d0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
97e0: 65 77 2c 20 69 6e 74 20 64 69 72 53 79 6e 63 29  ew, int dirSync)
97f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
9800: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
9810: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
9820: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
9830: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
9840: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
9850: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
9860: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
9870: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
9880: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
9890: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
98a0: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
98b0: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
98c0: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
98d0: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
98e0: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
98f0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
9900: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
9910: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
9920: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
9930: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
9940: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
9950: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
9960: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
9970: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
9980: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
9990: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
99a0: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
99b0: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
99c0: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
99d0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
99e0: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
99f0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
9a00: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
9a10: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9a20: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
9a30: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
9a40: 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
9a50: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
9a60: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
9a70: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
9a80: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
9a90: 65 20 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72  e file is both r
9aa0: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
9ab0: 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  able..** With SQ
9ac0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9ad0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
9ae0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
9af0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
9b00: 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a  is readable..*/.
9b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9b20: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
9b30: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
9b40: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9b50: 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  E 1.#define SQLI
9b60: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
9b70: 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      2../*.** CAP
9b80: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
9b90: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
9ba0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
9bb0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
9bc0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
9bd0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
9be0: 67 20 73 74 61 74 65 73 20 74 68 61 74 0a 2a 2a  g states that.**
9bf0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 73 68 6d 20   an sqlite3_shm 
9c00: 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 69 6e  object can be in
9c10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
9c20: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
9c30: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
9c40: 51 4c 49 54 45 5f 53 48 4d 5f 52 45 41 44 20 20  QLITE_SHM_READ  
9c50: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
9c60: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52 45 41 44   SQLITE_SHM_READ
9c70: 5f 46 55 4c 4c 20 20 20 20 32 0a 23 64 65 66 69  _FULL    2.#defi
9c80: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 57 52  ne SQLITE_SHM_WR
9c90: 49 54 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  ITE        3.#de
9ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
9cb0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 34 0a 23  PENDING      4.#
9cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
9cd0: 4d 5f 43 48 45 43 4b 50 4f 49 4e 54 20 20 20 35  M_CHECKPOINT   5
9ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9cf0: 53 48 4d 5f 52 45 43 4f 56 45 52 20 20 20 20 20  SHM_RECOVER     
9d00: 20 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   6../*.** CAPI3R
9d10: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
9d20: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
9d30: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
9d40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9d50: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
9d60: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
9d70: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
9d80: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
9d90: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
9da0: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
9db0: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
9dc0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
9dd0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
9de0: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
9df0: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
9e00: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
9e10: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
9e20: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
9e30: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
9e40: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
9e50: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
9e60: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
9e70: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
9e80: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
9e90: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
9ea0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
9eb0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
9ec0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9ed0: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
9ee0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
9ef0: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
9f00: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
9f10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
9f20: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
9f30: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
9f40: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
9f50: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
9f60: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
9f70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
9f80: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
9f90: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
9fa0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9fb0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
9fc0: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
9fd0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
9fe0: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
9ff0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
a000: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
a010: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
a020: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
a030: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
a040: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
a050: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
a060: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
a070: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
a080: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
a090: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
a0a0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
a0b0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
a0c0: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
a0d0: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
a0e0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
a0f0: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
a100: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
a110: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
a120: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
a130: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
a140: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
a150: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a160: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a170: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
a180: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
a190: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
a1a0: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
a1b0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a1c0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
a1d0: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
a1e0: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
a1f0: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
a200: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
a210: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
a220: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
a230: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
a240: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
a250: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
a260: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
a270: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
a280: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
a290: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
a2a0: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
a2b0: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
a2c0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
a2d0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
a2e0: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
a2f0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
a300: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
a310: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
a320: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
a330: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
a340: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
a350: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
a360: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
a370: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
a380: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a390: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
a3a0: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
a3b0: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
a3c0: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
a3d0: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
a3e0: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
a3f0: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
a400: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
a410: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
a420: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
a430: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
a440: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a450: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
a460: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
a470: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
a480: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
a490: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
a4a0: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
a4b0: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
a4c0: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
a4d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a4e0: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
a4f0: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
a500: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
a510: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
a520: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
a530: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
a540: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
a550: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
a560: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
a570: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
a580: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
a590: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
a5a0: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
a5b0: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
a5c0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
a5d0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
a5e0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
a5f0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
a600: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
a610: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
a620: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
a630: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
a640: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
a650: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
a660: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
a670: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
a680: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
a690: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
a6a0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
a6b0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
a6c0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
a6d0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
a6e0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
a6f0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
a700: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a710: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
a720: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
a730: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
a740: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
a750: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
a760: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
a770: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
a780: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
a790: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
a7a0: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
a7b0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
a7c0: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
a7d0: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
a7e0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
a7f0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
a800: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
a810: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
a820: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a830: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
a840: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
a850: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
a860: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
a870: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
a880: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
a890: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
a8a0: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
a8b0: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
a8c0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a8d0: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
a8e0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
a8f0: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
a900: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
a910: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
a920: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
a930: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
a940: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
a950: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
a960: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
a970: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
a980: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
a990: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
a9a0: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
a9b0: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
a9c0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
a9d0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
a9e0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
a9f0: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
aa00: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
aa10: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
aa20: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
aa30: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
aa40: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
aa50: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
aa60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
aa70: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
aa80: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
aa90: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
aaa0: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
aab0: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
aac0: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
aad0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
aae0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
aaf0: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
ab00: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
ab10: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
ab20: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
ab30: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
ab40: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
ab50: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
ab60: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
ab70: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
ab80: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
ab90: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
aba0: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
abb0: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
abc0: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
abd0: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
abe0: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
abf0: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
ac00: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
ac10: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
ac20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
ac30: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
ac40: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ac50: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
ac60: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
ac70: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
ac80: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
ac90: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
aca0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
acb0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
acc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
acd0: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
ace0: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
acf0: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
ad00: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
ad10: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
ad20: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ilure..*/.int sq
ad30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ad40: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
ad50: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
ad60: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
ad70: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69  os_init(void);.i
ad80: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nt sqlite3_os_en
ad90: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
ada0: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
adb0: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
adc0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
add0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
ade0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
adf0: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
ae00: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
ae10: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
ae20: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
ae30: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
ae40: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
ae50: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
ae60: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
ae70: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
ae80: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
ae90: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
aea0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
aeb0: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
aec0: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
aed0: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
aee0: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
aef0: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
af00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
af10: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
af20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
af30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
af40: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
af50: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
af60: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
af70: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
af80: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
af90: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
afa0: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
afb0: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
afc0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
afd0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
afe0: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
aff0: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
b000: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
b010: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
b020: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
b030: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
b040: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b050: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
b060: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
b070: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
b080: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
b090: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
b0a0: 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
b0b0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
b0c0: 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
b0d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
b0e0: 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
b0f0: 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
b100: 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
b110: 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
b120: 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
b130: 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
b140: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
b150: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
b160: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
b170: 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
b180: 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
b190: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
b1a0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
b1b0: 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
b1c0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
b1d0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
b1e0: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
b1f0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
b200: 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
b210: 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
b220: 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
b230: 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
b240: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
b250: 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
b260: 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49  ing on the [SQLI
b270: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
b280: 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75  THREAD | configu
b290: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
b2a0: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
b2b0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
b2c0: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
b2d0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
b2e0: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
b2f0: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
b300: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
b310: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
b320: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
b330: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
b340: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
b350: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
b360: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
b370: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
b380: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
b390: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
b3a0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
b3b0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
b3c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b3d0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
b3e0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
b3f0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
b400: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
b410: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
b420: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
b430: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
b440: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
b450: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
b460: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
b470: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
b480: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
b490: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
b4a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
b4b0: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
b4c0: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
b4d0: 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a  rgument).  The.*
b4e0: 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  * sqlite3_db_con
b4f0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
b500: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75  should only be u
b510: 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  sed immediately 
b520: 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74  after.** the dat
b530: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b540: 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e   is created usin
b550: 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  g [sqlite3_open(
b560: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
b570: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73  open16()], or [s
b580: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
b590: 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ].  .**.** The s
b5a0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
b5b0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
b5c0: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
b5d0: 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72   the.** configur
b5e0: 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20  ation verb - an 
b5f0: 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
b600: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
b610: 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68  .** aspect of th
b620: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
b630: 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
b640: 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
b650: 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20  The only choice 
b660: 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69  for this value i
b670: 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  s [SQLITE_DBCONF
b680: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a  IG_LOOKASIDE]..*
b690: 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20  * New verbs are 
b6a0: 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64  likely to be add
b6b0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
b6c0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
b6d0: 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61  .** Additional a
b6e0: 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20  rguments depend 
b6f0: 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a  on the verb..**.
b700: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
b710: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
b720: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
b730: 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
b740: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
b750: 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
b760: 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
b770: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
b780: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
b790: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
b7a0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
b7b0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
b7c0: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
b7d0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
b7e0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
b7f0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
b800: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
b810: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
b820: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
b830: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
b840: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
b850: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
b860: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
b870: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
b880: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
b890: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
b8a0: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
b8b0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
b8c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
b8d0: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
b8e0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
b8f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
b900: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
b910: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
b920: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
b930: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
b940: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
b950: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
b960: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
b970: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b980: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
b990: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
b9a0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
b9b0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
b9c0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
b9d0: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
b9e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
b9f0: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
ba00: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
ba10: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
ba20: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
ba30: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
ba40: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
ba50: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
ba60: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
ba70: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
ba80: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
ba90: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
baa0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
bab0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
bac0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
bad0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
bae0: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
baf0: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
bb00: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
bb10: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
bb20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bb30: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
bb40: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
bb50: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
bb60: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
bb70: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
bb80: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
bb90: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
bba0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
bbb0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
bbc0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
bbd0: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
bbe0: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
bbf0: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
bc00: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
bc10: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
bc20: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
bc30: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e  * The xMalloc an
bc40: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
bc50: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
bc60: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61  he.** malloc() a
bc70: 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
bc80: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
bc90: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
bca0: 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63  .** The xRealloc
bcb0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72   method must wor
bcc0: 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29  k like realloc()
bcd0: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
bce0: 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20  rd C library.** 
bcf0: 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69  with the excepti
bd00: 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73  on that if the s
bd10: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
bd20: 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65  o xRealloc is ze
bd30: 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  ro,.** xRealloc 
bd40: 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20  must be a no-op 
bd50: 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65  - it must not pe
bd60: 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61  rform any alloca
bd70: 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c  tion or.** deall
bd80: 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74  ocation.  ^SQLit
bd90: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
bda0: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
bdb0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
bdc0: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
bdd0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
bde0: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
bdf0: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20  to xRoundup..** 
be00: 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20  And so in cases 
be10: 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61  where xRoundup a
be20: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
be30: 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c  positive number,
be40: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e  .** xRealloc can
be50: 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79   perform exactly
be60: 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64   as the standard
be70: 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63   library realloc
be80: 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20  () and.** still 
be90: 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65  be in compliance
bea0: 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69   with this speci
beb0: 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  fication..**.** 
bec0: 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
bed0: 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
bee0: 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
bef0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
bf00: 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
bf10: 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
bf20: 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
bf30: 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
bf40: 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
bf50: 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
bf60: 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
bf70: 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
bf80: 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
bf90: 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
bfa0: 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
bfb0: 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
bfc0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
bfd0: 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
bfe0: 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
bff0: 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
c000: 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
c010: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
c020: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
c030: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
c040: 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
c050: 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
c060: 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
c070: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
c080: 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
c090: 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
c0a0: 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
c0b0: 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
c0c0: 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
c0d0: 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
c0e0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
c0f0: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
c100: 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
c110: 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
c120: 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
c130: 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
c140: 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
c150: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
c160: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
c170: 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
c180: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
c190: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
c1a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
c1b0: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (For example,.*
c1c0: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
c1d0: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
c1e0: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
c1f0: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
c200: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
c210: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
c220: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
c230: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
c240: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
c250: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
c260: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
c270: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
c280: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
c290: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
c2a0: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
c2b0: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
c2c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
c2d0: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
c2e0: 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
c2f0: 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
c300: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
c310: 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
c320: 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
c330: 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
c340: 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
c350: 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
c360: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
c370: 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
c380: 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
c390: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
c3a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c3b0: 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
c3c0: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
c3d0: 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
c3e0: 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
c3f0: 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
c400: 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
c410: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
c420: 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
c430: 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
c440: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
c450: 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
c460: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
c470: 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
c480: 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
c490: 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
c4a0: 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
c4b0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
c4c0: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
c4d0: 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
c4e0: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
c4f0: 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
c500: 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
c510: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
c520: 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
c530: 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
c540: 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
c550: 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
c560: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
c570: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
c580: 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
c590: 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
c5a0: 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
c5b0: 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
c5c0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
c5d0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
c5e0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
c5f0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
c600: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
c610: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
c620: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
c630: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
c640: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
c650: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
c660: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
c670: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
c680: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
c690: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
c6a0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
c6b0: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
c6c0: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
c6d0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
c6e0: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
c6f0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
c700: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
c710: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
c720: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
c730: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
c740: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
c750: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
c760: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
c770: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
c780: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
c790: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
c7a0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
c7b0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
c7c0: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
c7d0: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
c7e0: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
c7f0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
c800: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
c810: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
c820: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
c830: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
c840: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
c850: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
c860: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
c870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
c880: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
c890: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
c8a0: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
c8b0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
c8c0: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
c8d0: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
c8e0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
c8f0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
c900: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
c910: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
c920: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c930: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
c940: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
c950: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
c960: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
c970: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
c980: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
c990: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
c9a0: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
c9b0: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
c9c0: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
c9d0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
c9e0: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
c9f0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
ca00: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
ca10: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
ca20: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
ca30: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
ca40: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
ca50: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
ca60: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
ca70: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
ca80: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
ca90: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
caa0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cab0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
cac0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
cad0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
cae0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
caf0: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
cb00: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
cb10: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
cb20: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
cb30: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
cb40: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
cb50: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
cb60: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
cb70: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
cb80: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
cb90: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
cba0: 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
cbb0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
cbc0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
cbd0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
cbe0: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
cbf0: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
cc00: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
cc10: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
cc20: 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
cc30: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
cc40: 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
cc50: 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
cc60: 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
cc70: 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
cc80: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
cc90: 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
cca0: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
ccb0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
ccc0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
ccd0: 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
cce0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
ccf0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
cd00: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
cd10: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
cd20: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
cd30: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
cd40: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
cd50: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
cd60: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
cd70: 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
cd80: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
cd90: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
cda0: 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
cdb0: 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
cdc0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
cdd0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
cde0: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
cdf0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
ce00: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
ce10: 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
ce20: 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
ce30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ce40: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
ce50: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
ce60: 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
ce70: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
ce80: 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
ce90: 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
cea0: 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
ceb0: 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
cec0: 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
ced0: 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
cee0: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
cef0: 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
cf00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
cf10: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
cf20: 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
cf30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
cf40: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
cf50: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
cf60: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
cf70: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
cf80: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
cf90: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
cfa0: 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
cfb0: 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
cfc0: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
cfd0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
cfe0: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
cff0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
d000: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
d010: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
d020: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
d030: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d040: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
d050: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d060: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
d070: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
d080: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
d090: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
d0a0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
d0b0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
d0c0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
d0d0: 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
d0e0: 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
d0f0: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
d100: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
d110: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
d120: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
d130: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d140: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d150: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d160: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
d170: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
d180: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
d190: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
d1a0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d1b0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
d1c0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
d1d0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
d1e0: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
d1f0: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
d200: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d210: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
d220: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
d230: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
d240: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
d250: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
d260: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d270: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
d280: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
d290: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
d2a0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
d2b0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
d2c0: 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
d2d0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
d2e0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
d2f0: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
d300: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
d310: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
d320: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
d330: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
d340: 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
d350: 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
d360: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
d370: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d380: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
d390: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
d3a0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
d3b0: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
d3c0: 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
d3d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d3e0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
d3f0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
d400: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
d410: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
d420: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
d430: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
d440: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d450: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
d460: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
d470: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
d480: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
d490: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
d4a0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
d4b0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
d4c0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
d4d0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
d4e0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
d4f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d500: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
d510: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
d520: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
d530: 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
d540: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
d550: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
d560: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d570: 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
d580: 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
d590: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
d5a0: 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
d5b0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
d5c0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
d5d0: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
d5e0: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
d5f0: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
d600: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
d610: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
d620: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
d630: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
d640: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
d650: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
d660: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
d670: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
d680: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
d690: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
d6a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d6b0: 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
d6c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
d6d0: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
d6e0: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
d6f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d700: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
d710: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
d720: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
d730: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d740: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
d750: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
d760: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
d770: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d780: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
d790: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
d7a0: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
d7b0: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
d7c0: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
d7d0: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
d7e0: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
d7f0: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
d800: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
d810: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
d820: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d830: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
d840: 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
d850: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
d860: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
d870: 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
d880: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
d890: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
d8a0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
d8b0: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
d8c0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
d8d0: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
d8e0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
d8f0: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
d900: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
d910: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
d920: 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  imit()].**   <li
d930: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
d940: 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
d950: 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
d960: 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
d970: 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
d980: 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
d990: 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
d9a0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
d9b0: 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
d9c0: 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
d9d0: 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
d9e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
d9f0: 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
da00: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
da10: 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
da20: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
da30: 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
da40: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
da50: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
da60: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
da70: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
da80: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73  can use for.** s
da90: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
daa0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
dab0: 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f  arguments:  A po
dac0: 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
dad0: 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
dae0: 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
daf0: 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20 61  ich the scrach a
db00: 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
db10: 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
db20: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
db30: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
db40: 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
db50: 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
db60: 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
db70: 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
db80: 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
db90: 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
dba0: 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73  ple of 16. The s
dbb0: 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75  z parameter shou
dbc0: 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65  ld be a few byte
dbd0: 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e  s.** larger than
dbe0: 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61   the actual scra
dbf0: 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72  tch space requir
dc00: 65 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e  ed due to intern
dc10: 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20  al overhead..** 
dc20: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
dc30: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69  nt must be a poi
dc40: 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
dc50: 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72  e aligned buffer
dc60: 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20  .** of at least 
dc70: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
dc80: 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
dc90: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
dca0: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
dcb0: 63 68 20 62 75 66 66 65 72 20 70 65 72 20 74 68  ch buffer per th
dcc0: 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73  read.  So.** N s
dcd0: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
dce0: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
dcf0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
dd00: 68 72 65 61 64 73 2e 20 20 5e 53 51 4c 69 74 65  hreads.  ^SQLite
dd10: 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72   will.** never r
dd20: 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68  equire a scratch
dd30: 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
dd40: 6d 6f 72 65 20 74 68 61 6e 20 36 20 74 69 6d 65  more than 6 time
dd50: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
dd60: 2a 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66  * page size. ^If
dd70: 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
dd80: 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  eds additional s
dd90: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
dda0: 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20 69 73  yond .** what is
ddb0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
ddc0: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
ddd0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
dde0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ddf0: 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
de00: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
de10: 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
de20: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
de30: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
de40: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
de50: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
de60: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
de70: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
de80: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
de90: 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64  use for.** the d
dea0: 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
deb0: 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
dec0: 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ult page cache i
ded0: 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a  mplemenation.  .
dee0: 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
def0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
df00: 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
df10: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
df20: 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
df30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
df40: 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
df50: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
df60: 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a  _PCACHE option..
df70: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
df80: 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
df90: 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70  this option: A p
dfa0: 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65  ointer to 8-byte
dfb0: 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
dfc0: 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
dfd0: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
dfe0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
dff0: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
e000: 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
e010: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
e020: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
e030: 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
e040: 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
e050: 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
e060: 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29  n 512 and 32768)
e070: 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65   plus a little e
e080: 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a  xtra for each.**
e090: 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
e0a0: 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20  The page header 
e0b0: 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30  size is 20 to 40
e0c0: 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67   bytes depending
e0d0: 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20   on.** the host 
e0e0: 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e  architecture.  ^
e0f0: 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
e100: 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
e110: 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
e120: 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69   to make sz a li
e130: 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20  ttle too large. 
e140: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
e150: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
e160: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
e170: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
e180: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
e190: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
e1a0: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d  e will use the m
e1b0: 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62  emory provided b
e1c0: 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
e1d0: 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20  ment to satisfy 
e1e0: 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65  its.** memory ne
e1f0: 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73  eds for the firs
e200: 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69  t N pages that i
e210: 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e  t adds to cache.
e220: 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c    ^If additional
e230: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
e240: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
e250: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
e260: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
e270: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
e280: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
e290: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
e2a0: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
e2b0: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
e2c0: 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c  ce..** ^The impl
e2d0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
e2e0: 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65   use one or more
e2f0: 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72   of the N buffer
e300: 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65  s to hold .** me
e310: 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20  mory accounting 
e320: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65  information. The
e330: 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
e340: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
e350: 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
e360: 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
e370: 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
e380: 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
e390: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
e3a0: 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
e3b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
e3c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
e3d0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
e3e0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
e3f0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
e400: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
e410: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
e420: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
e430: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
e440: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
e450: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
e460: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
e470: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
e480: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
e490: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
e4a0: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
e4b0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
e4c0: 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
e4d0: 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
e4e0: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
e4f0: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
e500: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
e510: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
e520: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
e530: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
e540: 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
e550: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
e560: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
e570: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
e580: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
e590: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
e5a0: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
e5b0: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
e5c0: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
e5d0: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
e5e0: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
e5f0: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
e600: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
e610: 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
e620: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
e630: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
e640: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
e650: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
e660: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
e670: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
e680: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
e690: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
e6a0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
e6b0: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
e6c0: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
e6d0: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
e6e0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
e6f0: 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
e700: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
e710: 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
e720: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
e730: 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
e740: 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
e750: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
e760: 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
e770: 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
e780: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e790: 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
e7a0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
e7b0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
e7c0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
e7d0: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
e7e0: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
e7f0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
e800: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
e810: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
e820: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
e830: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
e840: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
e850: 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
e860: 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
e870: 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
e880: 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
e890: 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
e8a0: 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
e8b0: 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
e8c0: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
e8d0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
e8e0: 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
e8f0: 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
e900: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e910: 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
e920: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
e930: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
e940: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
e950: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
e960: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
e970: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
e980: 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
e990: 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
e9a0: 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
e9b0: 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
e9c0: 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
e9d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
e9e0: 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
e9f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
ea00: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
ea10: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
ea20: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
ea30: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
ea40: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
ea50: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
ea60: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
ea70: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
ea80: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
ea90: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
eaa0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
eab0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
eac0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
ead0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
eae0: 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
eaf0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
eb00: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
eb10: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
eb20: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
eb30: 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
eb40: 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
eb50: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
eb60: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
eb70: 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
eb80: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
eb90: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
eba0: 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
ebb0: 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
ebc0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
ebd0: 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
ebe0: 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
ebf0: 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
ec00: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
ec10: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
ec20: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
ec30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
ec40: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
ec50: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
ec60: 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
ec70: 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
ec80: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
ec90: 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
eca0: 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
ecb0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
ecc0: 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
ecd0: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
ece0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ecf0: 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
ed00: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
ed10: 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ].</dd>.**.** <d
ed20: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ed30: 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
ed40: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
ed50: 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
ed60: 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
ed70: 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
ed80: 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
ed90: 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
eda0: 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
edb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
edc0: 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
edd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
ede0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
edf0: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
ee00: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
ee10: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
ee20: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
ee30: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
ee40: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
ee50: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
ee60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
ee70: 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
ee80: 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
ee90: 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
eea0: 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
eeb0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
eec0: 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
eed0: 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
eee0: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
eef0: 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
ef00: 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
ef10: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
ef20: 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
ef30: 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
ef40: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
ef50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
ef60: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
ef70: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
ef80: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
ef90: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
efa0: 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
efb0: 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
efc0: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
efd0: 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
efe0: 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
eff0: 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
f000: 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
f010: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
f020: 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
f030: 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
f040: 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
f050: 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
f060: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
f070: 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
f080: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f090: 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
f0a0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
f0b0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
f0c0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
f0d0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
f0e0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
f0f0: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
f100: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
f110: 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
f120: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
f130: 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
f140: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
f150: 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
f160: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
f170: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
f180: 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  G</dt>.** <dd> ^
f190: 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
f1a0: 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
f1b0: 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
f1c0: 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
f1d0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
f1e0: 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
f1f0: 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
f200: 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
f210: 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
f220: 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
f230: 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
f240: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
f250: 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
f260: 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
f270: 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
f280: 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
f290: 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
f2a0: 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
f2b0: 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
f2c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
f2d0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
f2e0: 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
f2f0: 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
f300: 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
f310: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
f320: 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
f330: 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
f340: 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
f350: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
f360: 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
f370: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
f380: 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
f390: 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
f3a0: 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
f3b0: 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
f3c0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
f3d0: 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
f3e0: 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
f3f0: 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
f400: 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
f410: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
f420: 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
f430: 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
f440: 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
f450: 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
f460: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
f470: 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
f480: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
f490: 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
f4a0: 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
f4b0: 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
f4c0: 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
f4d0: 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
f4e0: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
f4f0: 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
f500: 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
f510: 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
f520: 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
f530: 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
f540: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
f550: 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
f560: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
f570: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
f580: 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
f590: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
f5a0: 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
f5b0: 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
f5c0: 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
f5d0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
f5e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f5f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
f600: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
f610: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f620: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
f630: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
f640: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
f650: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
f660: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
f670: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
f680: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
f690: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
f6a0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
f6b0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f6c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
f6d0: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
f6e0: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
f6f0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
f700: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f710: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
f720: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
f730: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
f740: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f750: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
f760: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
f770: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
f780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f790: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
f7a0: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
f7b0: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
f7c0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
f7d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
f7e0: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
f7f0: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
f800: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f810: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
f820: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
f830: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
f840: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f850: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
f860: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
f870: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
f880: 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
f890: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
f8a0: 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
f8b0: 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
f8c0: 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
f8d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
f8e0: 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
f8f0: 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
f900: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f910: 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
f920: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
f930: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
f940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f950: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
f960: 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33    15  /* sqlite3
f970: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
f980: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f990: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
f9a0: 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
f9b0: 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f  unc, void* */../
f9c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
f9d0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
f9e0: 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
f9f0: 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
fa00: 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
fa10: 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
fa20: 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
fa30: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
fa40: 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
fa50: 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
fa60: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
fa70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
fa80: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
fa90: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
faa0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fab0: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
fac0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
fad0: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
fae0: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
faf0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
fb00: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
fb10: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
fb20: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
fb30: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
fb40: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
fb50: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
fb60: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
fb70: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
fb80: 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
fb90: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fba0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
fbb0: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
fbc0: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
fbd0: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
fbe0: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
fbf0: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
fc00: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
fc10: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
fc20: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
fc30: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
fc40: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
fc50: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
fc60: 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
fc70: 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
fc80: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
fc90: 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
fca0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
fcb0: 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
fcc0: 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
fcd0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
fce0: 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
fcf0: 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
fd00: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
fd10: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
fd20: 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
fd30: 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f  inter to an memo
fd40: 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
fd50: 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
fd60: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
fd70: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
fd80: 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
fd90: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
fda0: 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
fdb0: 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
fdc0: 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
fdd0: 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
fde0: 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
fdf0: 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
fe00: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
fe10: 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
fe20: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
fe30: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
fe40: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
fe50: 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
fe60: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
fe70: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
fe80: 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
fe90: 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
fea0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
feb0: 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
fec0: 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
fed0: 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
fee0: 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
fef0: 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
ff00: 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
ff10: 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
ff20: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
ff30: 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
ff40: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ff50: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
ff60: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
ff70: 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
ff80: 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
ff90: 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
ffa0: 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
ffb0: 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
ffc0: 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66  r.** multiple of
ffd0: 20 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b   8.  See also: [
ffe0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
fff0: 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a  OKASIDE]</dd>.**
10000 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
10010 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
10020 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
10030 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
10040 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a   int int */.../*
10050 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
10060 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
10070 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
10080 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
10090 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
100a0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
100b0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
100c0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
100d0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
100e0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
100f0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
10100 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
10110 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
10120 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
10130 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
10140 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
10150 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
10160 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
10170 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
10180 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
10190 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
101a0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
101b0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
101c0 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
101d0 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
101e0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
101f0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
10200 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
10210 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
10220 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
10230 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
10240 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
10250 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
10260 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
10270 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
10280 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
10290 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
102a0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
102b0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
102c0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
102d0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
102e0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
102f0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
10300 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
10310 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
10320 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
10330 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
10340 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
10350 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
10360 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
10370 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
10380 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
10390 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
103a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
103b0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
103c0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
103d0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
103e0 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
103f0 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
10400 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
10410 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
10420 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
10430 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
10440 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
10450 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
10460 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
10470 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
10480 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
10490 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
104a0 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
104b0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
104c0 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
104d0 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
104e0 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
104f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10500 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
10510 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
10520 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
10530 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
10540 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a  rigger fired.)^.
10550 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
10560 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
10570 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
10580 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
10590 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
105a0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
105b0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
105c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
105d0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
105e0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
105f0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
10600 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
10610 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
10620 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
10630 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
10640 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
10650 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
10660 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
10670 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
10680 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
10690 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
106a0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
106b0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
106c0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
106d0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
106e0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
106f0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
10700 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
10710 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
10720 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
10730 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
10740 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
10750 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
10760 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
10770 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
10780 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
10790 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
107a0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
107b0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
107c0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
107d0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
107e0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
107f0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
10800 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
10810 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
10820 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
10830 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
10840 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
10850 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
10860 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
10870 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
10880 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
10890 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
108a0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
108b0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
108c0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
108d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
108e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
108f0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
10900 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
10910 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
10920 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
10930 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
10940 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10950 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
10960 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
10970 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
10980 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
10990 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
109a0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
109b0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
109c0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
109d0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
109e0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
109f0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
10a00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10a10 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
10a20 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
10a30 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
10a40 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
10a50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
10a60 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
10a70 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
10a80 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
10a90 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
10aa0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
10ab0 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
10ac0 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
10ad0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10ae0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
10af0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10b00 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
10b10 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
10b20 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
10b30 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
10b40 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
10b50 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
10b60 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
10b70 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
10b80 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
10b90 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
10ba0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
10bb0 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
10bc0 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
10bd0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
10be0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
10bf0 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
10c00 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
10c10 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
10c20 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
10c30 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
10c40 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
10c50 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
10c60 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
10c70 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
10c80 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
10c90 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
10ca0 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
10cb0 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
10cc0 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
10cd0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
10ce0 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
10cf0 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
10d00 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
10d10 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
10d20 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
10d30 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
10d40 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
10d50 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
10d60 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
10d70 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
10d80 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
10d90 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
10da0 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
10db0 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
10dc0 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
10dd0 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
10de0 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
10df0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
10e00 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
10e10 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
10e20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
10e30 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
10e40 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
10e50 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
10e60 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
10e70 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
10e80 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
10e90 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
10ea0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
10eb0 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
10ec0 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
10ed0 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
10ee0 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
10ef0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
10f00 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
10f10 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
10f20 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
10f30 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10f40 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
10f50 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
10f60 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
10f70 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
10f80 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
10f90 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
10fa0 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
10fb0 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
10fc0 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
10fd0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
10fe0 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
10ff0 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
11000 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
11010 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
11020 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11030 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
11040 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
11050 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
11060 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
11070 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
11080 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
11090 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
110a0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
110b0 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
110c0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
110d0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
110e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
110f0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
11100 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
11110 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
11120 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
11130 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
11140 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
11150 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
11160 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
11170 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
11180 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
11190 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
111a0 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
111b0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
111c0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
111d0 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
111e0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
111f0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
11200 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
11210 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
11220 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
11230 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
11240 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
11250 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
11260 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
11270 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
11280 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
11290 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
112a0 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
112b0 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
112c0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
112d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
112e0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
112f0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
11300 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
11310 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
11320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
11330 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
11340 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
11350 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
11360 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
11370 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
11380 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
11390 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
113a0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
113b0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
113c0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
113d0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
113e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
113f0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
11400 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11410 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
11420 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
11430 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
11440 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
11450 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
11460 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
11470 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
11480 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
11490 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
114a0 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
114b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
114c0 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
114d0 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
114e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
114f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
11500 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
11510 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
11520 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
11530 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
11540 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
11550 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
11560 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
11570 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
11580 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
11590 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
115a0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
115b0 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
115c0 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
115d0 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
115e0 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
115f0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
11600 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
11610 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
11620 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
11630 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
11640 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
11650 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
11660 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
11670 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
11680 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
11690 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
116a0 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
116b0 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
116c0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
116d0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
116e0 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
116f0 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
11700 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
11710 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
11720 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
11730 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
11740 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
11750 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
11760 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
11770 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
11780 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
11790 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
117a0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
117b0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
117c0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
117d0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
117e0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
117f0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
11800 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
11810 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11820 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11830 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11840 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
11850 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
11860 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
11870 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
11880 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
11890 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
118a0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
118b0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
118c0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
118d0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
118e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
118f0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
11900 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
11910 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
11920 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
11930 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
11940 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
11950 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
11960 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
11970 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
11980 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
11990 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
119a0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
119b0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
119c0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
119d0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
119e0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
119f0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
11a00 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
11a10 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
11a20 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
11a30 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
11a40 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
11a50 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
11a60 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
11a70 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
11a80 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
11a90 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
11aa0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
11ab0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
11ac0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
11ad0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
11ae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11af0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
11b00 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
11b10 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
11b20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
11b30 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
11b40 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
11b50 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
11b60 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
11b70 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
11b80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11b90 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
11ba0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
11bb0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
11bc0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
11bd0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
11be0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
11bf0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
11c00 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
11c10 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
11c20 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
11c30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
11c40 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
11c50 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
11c60 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
11c70 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
11c80 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
11c90 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
11ca0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
11cb0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
11cc0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
11cd0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
11ce0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
11cf0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
11d00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
11d10 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
11d20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
11d30 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
11d40 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
11d50 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
11d60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11d70 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
11d80 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
11d90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
11da0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
11db0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
11dc0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
11dd0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
11de0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
11df0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
11e00 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
11e10 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
11e20 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
11e30 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
11e40 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
11e50 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
11e60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
11e70 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
11e80 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
11e90 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
11ea0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
11eb0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
11ec0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
11ed0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
11ee0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
11ef0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
11f00 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
11f10 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
11f20 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
11f30 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
11f40 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
11f50 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
11f60 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
11f70 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
11f80 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
11f90 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
11fa0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
11fb0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
11fc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
11fd0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
11fe0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
11ff0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
12000 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
12010 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
12020 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
12030 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
12040 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
12050 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
12060 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
12070 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
12080 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
12090 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
120a0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
120b0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
120c0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
120d0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
120e0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
120f0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
12100 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
12110 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
12120 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
12130 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
12140 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
12150 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
12160 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
12170 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
12180 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
12190 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
121a0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
121b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
121c0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
121d0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
121e0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
121f0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
12200 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
12210 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
12220 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
12230 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
12240 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
12250 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
12260 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
12270 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
12280 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
12290 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
122a0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
122b0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
122c0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
122d0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
122e0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
122f0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
12300 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
12310 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
12320 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
12330 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
12340 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
12350 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
12360 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
12370 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
12380 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
12390 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
123a0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
123b0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
123c0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
123d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
123e0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
123f0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
12400 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
12410 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
12420 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
12430 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
12440 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
12450 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
12460 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
12470 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
12480 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
12490 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
124a0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
124b0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
124c0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
124d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
124e0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
124f0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
12500 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
12510 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
12520 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
12530 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
12540 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
12550 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
12560 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
12570 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
12580 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
12590 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
125a0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
125b0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
125c0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
125d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
125e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
125f0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
12600 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
12610 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
12620 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
12630 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
12640 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
12650 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
12660 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
12670 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
12680 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
12690 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
126a0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
126b0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
126c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
126d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
126e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
126f0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
12700 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
12710 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
12720 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ors.**.** ^This 
12730 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
12740 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
12750 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
12760 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a  nvoked whenever.
12770 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
12780 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20   made to open a 
12790 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74  database table t
127a0 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hat another thre
127b0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
127c0 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a   has locked..**.
127d0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
127e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
127f0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
12800 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
12810 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
12820 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  * is returned im
12830 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65  mediately upon e
12840 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20  ncountering the 
12850 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62  lock.  ^If the b
12860 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  usy callback.** 
12870 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65  is not NULL, the
12880 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d  n the callback m
12890 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
128a0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
128b0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ts..**.** ^The f
128c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
128d0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
128e0 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  r is a copy of t
128f0 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72  he void* pointer
12900 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
12910 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
12920 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  to sqlite3_busy_
12930 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65  handler().  ^The
12940 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12950 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20   to.** the busy 
12960 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
12970 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
12980 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65  f times that the
12990 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61   busy handler ha
129a0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65  s.** been invoke
129b0 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69  d for this locki
129c0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
129d0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
129e0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
129f0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
12a00 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
12a10 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
12a20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
12a30 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
12a40 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
12a50 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74  _BLOCKED] is ret
12a60 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  urned..** ^If th
12a70 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
12a80 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
12a90 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
12aa0 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
12ab0 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
12ac0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
12ad0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
12ae0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
12af0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
12b00 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
12b10 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
12b20 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
12b30 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
12b40 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
12b50 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
12b60 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
12b70 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
12b80 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
12b90 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
12ba0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
12bb0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
12bc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
12bd0 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  USY].** or [SQLI
12be0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12bf0 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  ] instead of inv
12c00 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68  oking the busy h
12c10 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
12c20 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
12c30 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
12c40 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
12c50 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
12c60 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
12c70 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
12c80 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
12c90 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
12ca0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
12cb0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
12cc0 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
12cd0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
12ce0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
12cf0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
12d00 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
12d10 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
12d20 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
12d30 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
12d40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
12d50 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
12d60 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
12d70 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
12d80 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
12d90 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
12da0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
12db0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
12dc0 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
12dd0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
12de0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
12df0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
12e00 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
12e10 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
12e20 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
12e30 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
12e40 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
12e50 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
12e60 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
12e70 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
12e80 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
12e90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
12ea0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
12eb0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
12ec0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
12ed0 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
12ee0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
12ef0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
12f00 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
12f10 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
12f20 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
12f30 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
12f40 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
12f50 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
12f60 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
12f70 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
12f80 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
12f90 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
12fa0 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
12fb0 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
12fc0 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
12fd0 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
12fe0 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
12ff0 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
13000 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
13010 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
13020 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
13030 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
13040 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
13050 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61  .  ^If it is una
13060 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
13070 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
13080 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
13090 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
130a0 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
130b0 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
130c0 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
130d0 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
130e0 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
130f0 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
13100 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
13110 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
13120 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13130 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72  CKED].  ^This er
13140 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69  ror code promoti
13150 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20  on.** forces an 
13160 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61  automatic rollba
13170 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65  ck of the change
13180 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c  s.  See the.** <
13190 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63  a href="/cvstrac
131a0 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69  /wiki?p=Corrupti
131b0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
131c0 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70  rror">.** Corrup
131d0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
131e0 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20  yError</a> wiki 
131f0 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75  page for a discu
13200 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20  ssion of why.** 
13210 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e  this is importan
13220 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  t..**.** ^(There
13230 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
13240 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
13250 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
13260 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
13270 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
13280 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
13290 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
132a0 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
132b0 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
132c0 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
132d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
132e0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
132f0 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20  * will also set 
13300 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73  or clear the bus
13310 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
13320 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
13330 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
13340 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
13350 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
13360 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
13370 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
13380 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
13390 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20  dler.  Any such 
133a0 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
133b0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
133c0 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
133d0 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
133e0 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
133f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13400 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
13410 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13420 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
13430 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
13440 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
13450 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
13460 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
13470 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b  d*,int), void*);
13480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13490 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
134a0 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  eout.**.** ^This
134b0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
134c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
134d0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
134e0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
134f0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
13500 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
13510 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
13520 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
13530 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
13540 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
13550 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
13560 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
13570 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
13580 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
13590 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
135a0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
135b0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
135c0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
135d0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
135e0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
135f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
13600 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
13610 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
13620 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13630 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  KED]..**.** ^Cal
13640 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
13650 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
13660 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
13670 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
13680 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
13690 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
136a0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
136b0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
136c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
136d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
136e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
136f0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
13700 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
13710 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
13720 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
13730 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
13740 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13750 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
13760 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
13770 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
13780 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
13790 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
137a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
137b0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
137c0 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
137d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
137e0 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
137f0 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
13800 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44   Queries.**.** D
13810 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
13820 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
13830 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
13840 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
13850 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
13860 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13870 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
13880 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
13890 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
138a0 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
138b0 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
138c0 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
138d0 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
138e0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
138f0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
13900 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
13910 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
13920 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
13930 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
13940 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
13950 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
13960 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
13970 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
13980 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
13990 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
139a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
139b0 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
139c0 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
139d0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
139e0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
139f0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
13a00 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
13a10 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
13a20 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
13a30 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
13a40 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
13a50 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
13a60 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
13a70 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
13a80 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
13a90 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
13aa0 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
13ab0 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
13ac0 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
13ad0 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
13ae0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
13af0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
13b00 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
13b10 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
13b20 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
13b30 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
13b40 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
13b50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
13b60 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
13b70 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
13b80 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
13b90 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
13ba0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
13bb0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
13bc0 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
13bd0 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
13be0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
13bf0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
13c00 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
13c10 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
13c20 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
13c30 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
13c40 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
13c50 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13c60 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
13c70 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
13c80 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
13c90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
13ca0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
13cb0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
13cc0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
13cd0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
13ce0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
13cf0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
13d00 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
13d10 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
13d20 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
13d30 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
13d40 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
13d50 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
13d60 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
13d70 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
13d80 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
13d90 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
13da0 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
13db0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
13dc0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
13dd0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
13de0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
13df0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
13e00 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
13e10 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
13e20 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
13e30 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
13e40 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
13e50 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
13e60 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
13e70 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
13e80 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
13e90 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
13ea0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
13eb0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
13ec0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13ed0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
13ee0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
13ef0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
13f00 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
13f10 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
13f20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
13f30 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
13f40 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
13f50 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
13f60 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  >.**.** ^The sql
13f70 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13f80 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
13f90 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
13fa0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
13fb0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
13fc0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
13fd0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
13fe0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
13ff0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
14000 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
14010 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
14020 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
14030 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
14040 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
14050 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
14060 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
14070 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
14080 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
14090 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
140a0 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73 20   it should pass 
140b0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
140c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
140d0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
140e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
140f0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
14100 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
14110 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
14120 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
14130 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14140 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
14150 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
14160 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
14170 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
14180 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
14190 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
141a0 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
141b0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
141c0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
141d0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
141e0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
141f0 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
14200 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
14210 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14220 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14230 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
14240 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
14250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
14260 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
14270 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
14280 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
14290 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
142a0 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
142b0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
142c0 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
142d0 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
142e0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
142f0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
14300 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
14310 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
14320 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
14330 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
14340 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
14350 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
14360 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
14370 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
14380 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
14390 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
143a0 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
143b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
143c0 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .)^.*/.int sqlit
143d0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
143e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
143f0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
14400 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
14410 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
14420 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
14430 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
14440 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
14450 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
14460 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
14470 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
14480 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
14490 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
144a0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
144b0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
144c0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
144d0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
144e0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
144f0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
14500 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
14510 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
14520 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
14530 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
14540 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
14550 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
14560 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
14570 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
14580 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
14590 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
145a0 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
145b0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
145c0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
145d0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
145e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
145f0 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  brary..**.** ^Th
14600 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
14610 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
14620 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
14630 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
14640 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
14650 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
14660 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
14670 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
14680 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
14690 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
146a0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
146b0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
146c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
146d0 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
146e0 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
146f0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
14700 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14710 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
14720 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
14730 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
14740 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
14750 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ring..**.** ^(In
14760 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
14770 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
14780 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
14790 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
147a0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
147b0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
147c0 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
147d0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
147e0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
147f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14800 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
14810 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
14820 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
14830 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
14840 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
14850 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
14860 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
14870 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
14880 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
14890 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
148a0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
148b0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
148c0 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
148d0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
148e0 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
148f0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
14900 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
14910 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
14920 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
14930 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
14940 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
14950 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
14960 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
14970 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
14980 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
14990 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
149a0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
149b0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
149c0 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
149d0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
149e0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
149f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
14a00 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14a10 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
14a20 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
14a30 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
14a40 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
14a50 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
14a60 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
14a70 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
14a80 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
14a90 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
14aa0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
14ab0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
14ac0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
14ad0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
14ae0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
14af0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
14b00 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
14b10 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
14b20 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
14b30 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
14b40 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
14b50 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
14b60 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
14b70 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  racters..**.** T
14b80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c  hese routines al
14b90 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65  l implement some
14ba0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d   additional form
14bb0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e  atting.** option
14bc0 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75  s that are usefu
14bd0 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69  l for constructi
14be0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
14bf0 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65  s..** All of the
14c00 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20   usual printf() 
14c10 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
14c20 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64  ns apply.  In ad
14c30 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a  dition, there.**
14c40 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25   is are "%q", "%
14c50 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  Q", and "%z" opt
14c60 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
14c70 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
14c80 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
14c90 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
14ca0 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
14cb0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
14cc0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
14cd0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
14ce0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
14cf0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
14d00 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
14d10 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
14d20 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
14d30 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
14d40 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
14d50 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
14d60 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
14d70 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
14d80 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
14d90 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
14da0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
14db0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
14dc0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
14dd0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
14de0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
14df0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
14e00 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
14e10 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
14e20 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
14e30 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
14e40 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
14e50 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
14e60 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
14e70 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
14e80 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
14e90 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14ea0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
14eb0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
14ec0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
14ed0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
14ee0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
14ef0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
14f00 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
14f10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
14f20 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
14f30 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
14f40 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
14f50 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
14f60 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
14f70 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
14f80 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
14f90 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
14fa0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
14fb0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
14fc0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
14fd0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
14fe0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
14ff0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
15000 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
15010 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
15020 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
15030 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
15040 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
15050 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
15060 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
15070 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
15080 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15090 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
150a0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
150b0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
150c0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
150d0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
150e0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
150f0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
15100 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
15110 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
15120 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
15130 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
15140 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
15150 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
15160 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
15170 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
15180 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
15190 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
151a0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
151b0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
151c0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
151d0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
151e0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
151f0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
15200 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
15210 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
15220 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
15230 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
15240 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
15250 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
15260 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
15270 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
15280 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
15290 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
152a0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
152b0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
152c0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
152d0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
152e0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
152f0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
15300 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
15310 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
15320 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
15330 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
15340 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15350 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
15360 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
15370 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
15380 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
15390 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
153a0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
153b0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
153c0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
153d0 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
153e0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
153f0 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
15400 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
15410 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
15420 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
15430 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
15440 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
15450 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
15460 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
15470 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
15480 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
15490 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
154a0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
154b0 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
154c0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
154d0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
154e0 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
154f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
15500 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
15510 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  r*, ...);../*.**
15520 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
15530 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
15540 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
15550 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
15560 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
15570 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
15580 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
15590 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
155a0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
155b0 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
155c0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
155d0 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
155e0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
155f0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
15600 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
15610 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
15620 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
15630 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
15640 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
15650 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
15660 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
15670 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
15680 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
15690 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
156a0 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
156b0 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
156c0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
156d0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
156e0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
156f0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
15700 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
15710 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
15720 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
15730 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
15740 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
15750 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
15760 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
15770 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
15780 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
15790 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
157a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
157b0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
157c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
157d0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
157e0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
157f0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
15800 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
15810 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
15820 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
15830 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
15840 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
15850 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
15860 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
15870 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
15880 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
15890 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
158a0 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
158b0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
158c0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
158d0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
158e0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
158f0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
15900 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
15910 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
15920 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
15930 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
15940 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
15950 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
15960 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
15970 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
15980 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
15990 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
159a0 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
159b0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
159c0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
159d0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
159e0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
159f0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
15a00 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
15a10 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
15a20 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
15a30 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
15a40 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
15a50 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72   ^(The sqlite3_r
15a60 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
15a70 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
15a80 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
15a90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15aa0 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
15ab0 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
15ac0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
15ad0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
15ae0 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
15af0 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
15b00 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
15b10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e  .** parameter.)^
15b20 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20   ^ If the first 
15b30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
15b40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
15b50 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
15b60 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
15b70 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
15b80 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
15b90 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15ba0 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
15bb0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15bc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
15bd0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20  alloc()..** ^If 
15be0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15bf0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
15c00 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
15c10 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
15c20 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
15c30 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
15c40 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
15c50 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
15c60 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
15c70 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15c80 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
15c90 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71  ealloc()..** ^sq
15ca0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15cb0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
15cc0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
15cd0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
15ce0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
15cf0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
15d00 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
15d10 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
15d20 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
15d30 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
15d40 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
15d50 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
15d60 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
15d70 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
15d80 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
15d90 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
15da0 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
15db0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
15dc0 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
15dd0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
15de0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
15df0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
15e00 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
15e10 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
15e20 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
15e30 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
15e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
15e50 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
15e60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
15e70 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
15e80 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
15e90 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
15ea0 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
15eb0 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  boundary..**.** 
15ec0 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
15ed0 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
15ee0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
15ef0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
15f00 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
15f10 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
15f20 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
15f30 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
15f40 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
15f50 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
15f60 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
15f70 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
15f80 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
15f90 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
15fa0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
15fb0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
15fc0 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
15fd0 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f  ** The Windows O
15fe0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
15ff0 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73  r calls.** the s
16000 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
16010 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
16020 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
16030 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
16040 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
16050 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
16060 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
16070 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
16080 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
16090 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
160a0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
160b0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
160c0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
160d0 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74  n errors are det
160e0 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
160f0 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ey are reported 
16100 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
16110 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
16120 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
16130 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
16140 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
16150 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
16160 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
16170 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
16180 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16190 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
161a0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
161b0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
161c0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
161d0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
161e0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
161f0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
16200 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
16210 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
16220 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
16230 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
16240 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
16250 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
16260 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
16270 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
16280 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
16290 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
162a0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
162b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
162c0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
162d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
162e0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
162f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
16300 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
16310 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
16320 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
16330 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
16340 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
16350 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
16360 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
16370 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
16380 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
16390 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
163a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
163b0 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
163c0 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
163d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
163e0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
163f0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
16400 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
16410 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
16420 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
16430 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16440 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
16450 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
16460 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
16470 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
16480 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
16490 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
164a0 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
164b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
164c0 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
164d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
164e0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
164f0 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
16500 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
16510 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
16520 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
16530 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
16540 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
16550 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
16560 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
16570 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
16580 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
16590 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
165a0 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
165b0 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
165c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
165d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
165e0 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
165f0 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
16600 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
16610 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
16620 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
16630 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
16640 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
16650 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
16660 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
16670 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
16680 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
16690 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
166a0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
166b0 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
166c0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
166d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
166e0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
166f0 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
16700 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
16710 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
16720 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
16730 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
16740 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
16750 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
16760 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
16770 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16780 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
16790 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
167a0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
167b0 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
167c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
167d0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
167e0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
167f0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  r.**.** SQLite c
16800 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
16810 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
16820 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
16830 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
16840 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
16850 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52  andom [ROWID | R
16860 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65  OWIDs] when inse
16870 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64  rting new record
16880 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74  s into a table t
16890 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75  hat.** already u
168a0 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20  ses the largest 
168b0 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d  possible [ROWID]
168c0 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61  .  The PRNG is a
168d0 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  lso used for.** 
168e0 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e  the build-in ran
168f0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d  dom() and random
16900 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74  blob() SQL funct
16910 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65  ions.  This inte
16920 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20  rface allows.** 
16930 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20  applications to 
16940 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20  access the same 
16950 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70  PRNG for other p
16960 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  urposes..**.** ^
16970 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  A call to this r
16980 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20  outine stores N 
16990 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
169a0 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ess into buffer 
169b0 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  P..**.** ^The fi
169c0 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
169d0 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
169e0 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
169f0 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
16a00 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
16a10 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
16a20 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
16a30 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
16a40 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
16a50 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
16a60 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
16a70 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
16a80 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71  * ^On all subseq
16a90 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73  uent invocations
16aa0 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  , the pseudo-ran
16ab0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
16ac0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
16ad0 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
16ae0 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
16af0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
16b00 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
16b10 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  od..*/.void sqli
16b20 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
16b30 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
16b40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16b50 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
16b60 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
16b70 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  backs.**.** ^Thi
16b80 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
16b90 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72  ers a authorizer
16ba0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
16bb0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
16bc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16bd0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
16be0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
16bf0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
16c00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16c10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
16c20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
16c30 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
16c40 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
16c50 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
16c60 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
16c70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16c80 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
16c90 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
16ca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16cb0 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
16cc0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
16cd0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
16ce0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
16cf0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
16d00 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
16d10 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
16d20 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
16d30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16d40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
16d50 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
16d60 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
16d70 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
16d80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16d90 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
16da0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
16db0 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
16dc0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
16dd0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
16de0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
16df0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
16e00 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
16e10 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
16e20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
16e30 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
16e40 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
16e50 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
16e60 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
16e70 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
16e80 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
16e90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16ea0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
16eb0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
16ec0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
16ed0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
16ee0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
16ef0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
16f00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16f10 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
16f20 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
16f30 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
16f40 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
16f50 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
16f60 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
16f70 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
16f80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
16f90 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
16fa0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
16fb0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
16fc0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
16fd0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
16fe0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
16ff0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
17000 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
17010 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
17020 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
17030 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
17040 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
17050 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
17060 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
17070 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
17080 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
17090 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
170a0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
170b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
170c0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
170d0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
170e0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
170f0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
17100 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
17110 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
17120 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
17130 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
17140 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
17150 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
17160 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
17170 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
17180 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
17190 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
171a0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
171b0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
171c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
171d0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
171e0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
171f0 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
17200 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
17210 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
17220 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
17230 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
17240 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
17250 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
17260 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
17270 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
17280 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
17290 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
172a0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
172b0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
172c0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
172d0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
172e0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
172f0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
17300 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
17310 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
17320 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
17330 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
17340 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
17350 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
17360 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
17370 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
17380 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
17390 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
173a0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
173b0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
173c0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
173d0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
173e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
173f0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
17400 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
17410 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
17420 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
17430 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
17440 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
17450 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
17460 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
17470 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
17480 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
17490 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
174a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
174b0 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
174c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
174d0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
174e0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
174f0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
17500 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
17510 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
17520 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
17530 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
17540 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
17550 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
17560 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
17570 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
17580 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
17590 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
175a0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
175b0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
175c0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
175d0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
175e0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
175f0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
17600 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
17610 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
17620 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
17630 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
17640 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
17650 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
17660 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
17670 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
17680 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
17690 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
176a0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
176b0 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
176c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
176d0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
176e0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
176f0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
17700 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
17710 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
17720 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
17730 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
17740 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
17750 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
17760 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
17770 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
17780 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
17790 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
177a0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
177b0 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
177c0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
177d0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
177e0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
177f0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
17800 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
17810 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
17820 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
17830 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
17840 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
17850 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
17860 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
17870 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
17880 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
17890 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
178a0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
178b0 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
178c0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
178d0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
178e0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
178f0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
17900 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
17910 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
17920 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
17930 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
17940 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
17950 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
17960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
17970 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
17980 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17990 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
179a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
179b0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
179c0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
179d0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
179e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
179f0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
17a00 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
17a10 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
17a20 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
17a30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17a40 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
17a50 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
17a60 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
17a70 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
17a80 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
17a90 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
17aa0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
17ab0 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
17ac0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
17ad0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
17ae0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
17af0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
17b00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17b10 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
17b20 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
17b30 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
17b40 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
17b50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17b60 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
17b70 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
17b80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17b90 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
17ba0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
17bb0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
17bc0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
17bd0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
17be0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
17bf0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
17c00 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
17c10 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
17c20 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
17c30 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
17c40 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
17c50 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
17c60 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
17c70 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
17c80 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
17c90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17ca0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
17cb0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
17cc0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
17cd0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
17ce0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
17cf0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
17d00 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
17d10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17d20 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
17d30 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
17d40 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
17d50 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
17d60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17d70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
17d80 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
17d90 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
17da0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
17db0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
17dc0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
17dd0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
17de0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
17df0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
17e00 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
17e10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17e20 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
17e30 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
17e40 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
17e50 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
17e60 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
17e70 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
17e80 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
17e90 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
17ea0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
17eb0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
17ec0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
17ed0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
17ee0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
17ef0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
17f00 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
17f10 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
17f20 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
17f30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17f40 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
17f50 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
17f60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
17f70 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
17f80 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
17f90 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
17fa0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
17fb0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
17fc0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17fd0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
17fe0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
17ff0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
18000 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
18010 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
18020 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
18030 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
18040 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
18050 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18060 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
18070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
18080 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
18090 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
180a0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
180b0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
180c0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
180d0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
180e0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
180f0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
18100 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
18110 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
18120 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
18130 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
18140 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
18150 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
18160 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
18170 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
18180 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
18190 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
181a0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
181b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
181c0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
181d0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
181e0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
181f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
18200 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18210 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
18220 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
18230 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
18240 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
18250 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
18260 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
18270 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
18280 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
18290 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
182a0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
182b0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
182c0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
182d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
182e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
182f0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
18300 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
18310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18320 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
18330 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
18340 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
18350 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18370 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
18380 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
18390 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
183a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
183b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
183c0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
183d0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
183e0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
183f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18400 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18410 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
18420 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
18430 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
18440 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18450 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18460 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
18470 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
18480 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
18490 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
184a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
184b0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
184c0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
184d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
184e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
184f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18500 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
18510 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
18520 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
18530 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18540 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
18550 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
18560 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
18570 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18580 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18590 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
185a0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
185b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
185c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
185d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
185e0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
185f0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
18600 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
18610 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18620 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18630 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
18640 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
18650 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18660 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18670 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18680 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
18690 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
186a0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
186b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
186c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
186d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
186e0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
186f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18700 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18710 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18720 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
18730 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
18740 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
18750 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
18760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18770 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
18780 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
18790 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
187a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
187b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
187c0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
187d0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
187e0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
187f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18810 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
18820 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
18830 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
18840 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18850 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
18860 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
18870 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
18880 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18890 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
188a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
188b0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
188c0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
188d0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
188e0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
188f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
18900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18910 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
18920 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
18930 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
18940 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
18950 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
18960 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
18970 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
18980 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18990 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
189a0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
189b0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
189c0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
189d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
189e0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
189f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
18a00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18a10 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
18a20 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18a30 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
18a40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
18a50 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
18a60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18a70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18a80 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
18a90 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
18aa0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
18ab0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
18ac0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18ad0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
18ae0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
18af0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
18b00 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18b10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18b20 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
18b30 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
18b40 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
18b50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18b60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18b70 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
18b80 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
18b90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18ba0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18bc0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
18bd0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
18be0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18bf0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
18c00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c10 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
18c20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
18c30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
18c40 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
18c50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18c60 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
18c70 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
18c80 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
18c90 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
18ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18cb0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
18cc0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
18cd0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
18ce0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
18cf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18d00 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
18d10 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
18d20 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
18d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
18d40 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
18d50 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
18d60 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
18d70 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
18d80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
18d90 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
18da0 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
18db0 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
18dc0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
18dd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
18de0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
18df0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
18e00 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
18e10 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
18e20 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
18e30 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
18e40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
18e50 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
18e60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
18e70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18e80 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
18e90 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
18ea0 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
18eb0 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
18ec0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
18ed0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
18ee0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
18ef0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
18f00 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
18f10 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
18f20 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
18f30 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
18f40 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
18f50 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
18f60 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
18f70 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
18f80 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
18f90 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
18fa0 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
18fb0 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
18fc0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18fd0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
18fe0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
18ff0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
19000 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
19010 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
19020 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
19030 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
19040 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
19050 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
19060 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
19070 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
19080 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
19090 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
190a0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f   took to run..*/
190b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
190c0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
190d0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
190e0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
190f0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
19100 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
19110 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
19120 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
19130 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
19140 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
19150 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
19160 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
19170 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
19180 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
19190 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
191a0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75   routine configu
191b0 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  res a callback f
191c0 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a  unction - the.**
191d0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
191e0 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76  ck - that is inv
191f0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
19200 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a  y during long.**
19210 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
19220 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
19230 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
19240 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  p()] and.** [sql
19250 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
19260 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  ].  An example u
19270 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
19280 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
19290 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
192a0 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
192b0 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49   query..**.** ^I
192c0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
192d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
192e0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
192f0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
19300 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
19310 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
19320 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
19330 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
19340 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
19350 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
19360 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
19370 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
19380 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
19390 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
193a0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
193b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
193c0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
193d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
193e0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
193f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19400 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
19410 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
19420 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
19430 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
19440 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
19450 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
19460 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
19470 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
19480 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
19490 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
194a0 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
194b0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
194c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
194d0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
194e0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
194f0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
19500 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
19510 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
19520 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
19530 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
19540 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
19550 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
19560 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
19570 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
19580 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
19590 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
195a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
195b0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
195c0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
195d0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
195e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
195f0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
19600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
19610 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
19620 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
19630 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
19640 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
19650 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
19660 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
19670 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
19680 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
19690 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
196a0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
196b0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
196c0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
196d0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
196e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
196f0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
19700 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
19710 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
19720 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
19730 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
19740 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
19750 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
19760 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
19770 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
19780 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
19790 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
197a0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
197b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
197c0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
197d0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
197e0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
197f0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
19800 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
19810 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
19820 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
19830 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
19840 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
19850 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
19860 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
19870 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
19880 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
19890 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
198a0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
198b0 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
198c0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
198d0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
198e0 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
198f0 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
19900 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
19910 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
19920 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
19930 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
19940 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
19950 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
19960 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19970 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
19980 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
19990 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
199a0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
199b0 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
199c0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
199d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
199e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
199f0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
19a00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
19a10 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
19a20 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
19a30 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
19a40 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
19a50 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
19a60 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
19a70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
19a80 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
19a90 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
19aa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
19ab0 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
19ac0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
19ad0 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
19ae0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
19af0 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
19b00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
19b10 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
19b20 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
19b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
19b40 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64  EDCACHE],.** and
19b50 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
19b60 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
19b70 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
19b80 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
19b90 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
19ba0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
19bb0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
19bc0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
19bd0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
19be0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
19bf0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
19c00 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
19c10 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
19c20 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
19c30 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
19c40 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
19c50 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
19c60 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
19c70 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
19c80 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
19c90 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
19ca0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
19cb0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
19cc0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
19cd0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
19ce0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
19cf0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
19d00 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
19d10 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
19d20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
19d30 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
19d40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
19d50 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
19d60 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
19d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
19d80 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
19d90 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
19da0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
19db0 73 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a  s creates it if.
19dc0 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
19dd0 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
19de0 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
19df0 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
19e00 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
19e10 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
19e20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
19e30 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
19e40 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
19e50 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
19e60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
19e70 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
19e80 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
19e90 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
19ea0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
19eb0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
19ec0 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
19ed0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
19ee0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
19ef0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
19f00 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20  _FULLMUTEX],.** 
19f10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
19f20 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72  REDCACHE] and/or
19f30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
19f40 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73  AREDCACHE] flags
19f50 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
19f60 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
19f70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
19f80 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
19f90 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
19fa0 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
19fb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19fc0 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
19fd0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
19fe0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
19ff0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
1a000 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
1a010 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
1a020 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
1a030 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1a040 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
1a050 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
1a060 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
1a070 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
1a080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a090 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
1a0a0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1a0b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
1a0c0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
1a0d0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
1a0e0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
1a0f0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1a100 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
1a110 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
1a120 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
1a130 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1a140 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a150 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
1a160 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
1a170 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1a180 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
1a190 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
1a1a0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
1a1b0 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
1a1c0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1a1d0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
1a1e0 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
1a1f0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1a200 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
1a210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a220 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
1a230 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
1a240 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
1a250 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
1a260 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
1a270 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1a280 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
1a290 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
1a2a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
1a2b0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
1a2c0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
1a2d0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1a2e0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
1a2f0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1a300 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1a310 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a320 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1a330 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1a340 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1a350 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1a360 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1a370 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1a380 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1a390 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1a3a0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1a3b0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1a3c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1a3d0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1a3e0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1a3f0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1a400 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1a410 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1a420 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1a430 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1a440 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1a450 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
1a460 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1a470 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1a480 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1a490 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1a4a0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1a4b0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1a4c0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
1a4d0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
1a4e0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1a4f0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
1a500 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
1a510 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1a520 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  osed..**.** ^The
1a530 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1a540 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1a550 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
1a560 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
1a570 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1a580 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
1a590 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1a5a0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
1a5b0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
1a5c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a5d0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
1a5e0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1a5f0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
1a600 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1a610 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
1a620 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1a630 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
1a640 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
1a650 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
1a660 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
1a670 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
1a680 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
1a690 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
1a6a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1a6b0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
1a6c0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
1a6d0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
1a6e0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
1a6f0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
1a700 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
1a710 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
1a720 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
1a730 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
1a740 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
1a750 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
1a760 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1a770 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
1a780 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  v2()..*/.int sql
1a790 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
1a7a0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1a7b0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1a7c0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1a7d0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1a7e0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
1a7f0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1a800 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
1a810 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
1a820 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
1a830 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1a840 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1a850 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
1a860 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
1a870 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
1a880 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
1a890 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1a8a0 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
1a8b0 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
1a8c0 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1a8d0 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
1a8e0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
1a8f0 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
1a900 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
1a910 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
1a920 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
1a930 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
1a940 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1a950 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
1a960 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
1a970 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
1a980 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
1a990 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
1a9a0 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  essages.**.** ^T
1a9b0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
1a9c0 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
1a9d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
1a9e0 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
1a9f0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1aa00 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
1aa10 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
1aa20 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
1aa30 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
1aa40 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
1aa50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1aa60 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
1aa70 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
1aa80 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
1aa90 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
1aaa0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
1aab0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1aac0 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
1aad0 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
1aae0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  fined.  ^The sql
1aaf0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1ab00 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
1ab10 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
1ab20 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1ab30 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
1ab40 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
1ab50 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
1ab60 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
1ab70 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
1ab80 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
1ab90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1aba0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
1abb0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1abc0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
1abd0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
1abe0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
1abf0 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
1ac00 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
1ac10 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
1ac20 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
1ac30 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
1ac40 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
1ac50 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
1ac60 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
1ac70 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
1ac80 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
1ac90 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
1aca0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
1acb0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
1acc0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
1acd0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
1ace0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
1acf0 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
1ad00 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
1ad10 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
1ad20 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
1ad30 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
1ad40 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
1ad50 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
1ad60 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
1ad70 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
1ad80 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
1ad90 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
1ada0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
1adb0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
1adc0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
1add0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
1ade0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
1adf0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
1ae00 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
1ae10 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
1ae20 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
1ae30 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
1ae40 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
1ae50 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
1ae60 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
1ae70 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
1ae80 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
1ae90 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
1aea0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
1aeb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aec0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
1aed0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
1aee0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
1aef0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
1af00 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
1af10 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
1af20 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
1af30 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
1af40 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
1af50 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
1af60 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
1af70 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
1af80 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
1af90 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
1afa0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
1afb0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
1afc0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
1afd0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
1afe0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
1aff0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
1b000 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
1b010 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
1b020 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
1b030 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
1b040 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
1b050 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
1b060 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
1b070 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
1b080 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1b090 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1b0a0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1b0b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
1b0c0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
1b0d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
1b0e0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
1b0f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b100 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
1b110 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
1b120 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
1b130 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
1b140 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
1b150 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
1b160 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
1b170 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
1b180 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
1b190 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
1b1a0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
1b1b0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
1b1c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
1b1d0 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
1b1e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
1b1f0 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
1b200 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
1b210 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
1b220 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
1b230 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
1b240 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1b250 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
1b260 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
1b270 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1b280 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1b290 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
1b2a0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
1b2b0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
1b2c0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
1b2d0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
1b2e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
1b2f0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
1b300 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
1b310 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
1b320 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1b330 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
1b340 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
1b350 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
1b360 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1b370 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
1b380 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
1b390 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
1b3a0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
1b3b0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1b3c0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
1b3d0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1b3e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
1b3f0 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
1b400 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
1b410 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
1b420 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
1b430 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1b440 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1b450 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1b460 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
1b470 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
1b480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1b490 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
1b4a0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
1b4b0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
1b4c0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
1b4d0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1b4e0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
1b4f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
1b500 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
1b510 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1b520 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1b530 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1b540 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
1b550 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
1b560 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
1b570 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1b580 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
1b590 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
1b5a0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
1b5b0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
1b5c0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1b5d0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
1b5e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1b5f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
1b600 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
1b610 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
1b620 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1b630 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29   the old limit.)
1b640 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
1b650 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1b660 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1b670 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1b680 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
1b690 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1b6a0 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1b6b0 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1b6c0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
1b6d0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1b6e0 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63  d].** set by a c
1b6f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72  ompile-time C pr
1b700 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1b710 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69   named .** [limi
1b720 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
1b730 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  XYZ]..** (The "_
1b740 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
1b750 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
1b760 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
1b770 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
1b780 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
1b790 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
1b7a0 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
1b7b0 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
1b7c0 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
1b7d0 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
1b7e0 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ** Run-time limi
1b7f0 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ts are intended 
1b800 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69  for use in appli
1b810 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e  cations that man
1b820 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69  age.** both thei
1b830 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64  r own internal d
1b840 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f  atabase and also
1b850 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20   databases that 
1b860 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a  are controlled.*
1b870 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65  * by untrusted e
1b880 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e  xternal sources.
1b890 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70    An example app
1b8a0 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62  lication might b
1b8b0 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73  e a.** web brows
1b8c0 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
1b8d0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
1b8e0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
1b8f0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
1b900 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
1b910 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
1b920 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
1b930 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
1b940 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
1b950 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
1b960 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
1b970 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
1b980 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
1b990 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
1b9a0 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
1b9b0 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
1b9c0 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
1b9d0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
1b9e0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
1b9f0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
1ba00 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
1ba10 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
1ba20 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
1ba30 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
1ba40 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1ba50 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
1ba60 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
1ba70 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
1ba80 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
1ba90 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1baa0 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
1bab0 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
1bac0 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
1bad0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
1bae0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1baf0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
1bb00 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
1bb10 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
1bb20 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
1bb30 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f  ure releases..*/
1bb40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
1bb50 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
1bb60 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
1bb70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1bb80 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
1bb90 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
1bba0 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
1bbb0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
1bbc0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
1bbd0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
1bbe0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
1bbf0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
1bc00 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
1bc10 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
1bc20 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
1bc30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1bc40 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
1bc50 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
1bc60 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
1bc70 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
1bc80 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
1bc90 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
1bca0 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
1bcb0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
1bcc0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
1bcd0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
1bce0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1bcf0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1bd00 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1bd10 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
1bd20 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
1bd30 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a  ble row.<dd>)^.*
1bd40 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1bd50 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1bd60 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1bd70 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1bd80 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1bd90 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
1bda0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1bdb0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1bdc0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1bdd0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1bde0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1bdf0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1be00 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1be10 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1be20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
1be30 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1be40 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1be50 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1be60 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1be70 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1be80 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
1be90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1bea0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1beb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1bec0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1bed0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1bee0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1bef0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1bf00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1bf10 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1bf20 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1bf30 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1bf40 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1bf50 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1bf60 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1bf70 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1bf80 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1bf90 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1bfa0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1bfb0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1bfc0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1bfd0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1bfe0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1bff0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1c000 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
1c010 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c020 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1c030 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
1c040 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c050 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
1c060 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
1c070 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c080 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
1c090 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
1c0a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c0b0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
1c0c0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
1c0d0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
1c0e0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c0f0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1c100 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1c110 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c120 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1c130 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1c140 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
1c150 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
1c160 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
1c170 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c180 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1c190 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
1c1a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c1b0 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62  number of variab
1c1c0 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  les in an SQL st
1c1d0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e  atement that can
1c1e0 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64  .** be bound.</d
1c1f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1c200 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
1c210 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
1c220 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c230 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
1c240 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
1c250 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
1c260 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
1c270 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1c280 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1c290 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
1c2a0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
1c2b0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
1c2c0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
1c2d0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1c2e0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
1c2f0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
1c300 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c310 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
1c320 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
1c330 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c340 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1c350 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
1c360 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c370 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
1c380 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
1c390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c3a0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
1c3b0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
1c3c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c3d0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
1c3e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
1c3f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c400 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
1c410 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
1c420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c430 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1c440 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
1c450 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
1c460 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
1c470 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
1c480 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
1c490 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
1c4a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
1c4b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
1c4c0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
1c4d0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
1c4e0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
1c4f0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
1c500 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
1c510 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
1c520 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
1c530 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
1c540 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
1c550 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
1c560 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
1c570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c580 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
1c590 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
1c5a0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
1c5b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1c5c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1c5d0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1c5e0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
1c5f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1c600 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
1c610 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
1c620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
1c630 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
1c640 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
1c650 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
1c660 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
1c670 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1c680 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
1c690 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1c6a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1c6b0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
1c6c0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
1c6d0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
1c6e0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
1c6f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1c700 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
1c710 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
1c720 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
1c730 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
1c740 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
1c750 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
1c760 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
1c770 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
1c780 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
1c790 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
1c7a0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
1c7b0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
1c7c0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
1c7d0 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
1c7e0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1c7f0 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
1c800 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
1c810 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
1c820 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
1c830 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
1c840 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
1c850 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
1c860 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
1c870 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
1c880 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
1c890 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
1c8a0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
1c8b0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
1c8c0 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
1c8d0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
1c8e0 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
1c8f0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
1c900 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
1c910 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
1c920 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
1c930 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1c940 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
1c950 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
1c960 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e  erminator bytes.
1c970 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
1c980 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
1c990 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
1c9a0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
1c9b0 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
1c9c0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
1c9d0 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
1c9e0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1c9f0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1ca00 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
1ca10 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
1ca20 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
1ca30 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
1ca40 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
1ca50 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
1ca60 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
1ca70 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
1ca80 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
1ca90 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
1caa0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1cab0 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
1cac0 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
1cad0 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
1cae0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
1caf0 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
1cb00 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
1cb10 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
1cb20 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
1cb30 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
1cb40 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
1cb50 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
1cb60 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
1cb70 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
1cb80 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
1cb90 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
1cba0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
1cbb0 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
1cbc0 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
1cbd0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1cbe0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1cbf0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1cc00 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
1cc10 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
1cc20 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
1cc30 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
1cc40 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1cc50 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
1cc60 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
1cc70 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
1cc80 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
1cc90 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
1cca0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1ccb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ccc0 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
1ccd0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
1cce0 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
1ccf0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
1cd00 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
1cd10 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
1cd20 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1cd30 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
1cd40 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1cd50 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
1cd60 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
1cd70 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
1cd80 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
1cd90 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
1cda0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
1cdb0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
1cdc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1cdd0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
1cde0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
1cdf0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
1ce00 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
1ce10 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
1ce20 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
1ce30 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
1ce40 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
1ce50 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
1ce60 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
1ce70 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
1ce80 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
1ce90 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
1cea0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
1ceb0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
1cec0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
1ced0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1cee0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
1cef0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
1cf00 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
1cf10 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
1cf20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e  run it again.  ^
1cf30 49 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61  If the schema ha
1cf40 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20  s changed in.** 
1cf50 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  a way that makes
1cf60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e   the statement n
1cf70 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20  o longer valid, 
1cf80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1cf90 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72   will still.** r
1cfa0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43  eturn [SQLITE_SC
1cfb0 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69  HEMA].  But unli
1cfc0 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  ke the legacy be
1cfd0 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f  havior, [SQLITE_
1cfe0 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f  SCHEMA] is.** no
1cff0 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e  w a fatal error.
1d000 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74    Calling [sqlit
1d010 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d020 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20   again will not 
1d030 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f  make the.** erro
1d040 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65  r go away.  Note
1d050 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65  : use [sqlite3_e
1d060 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64  rrmsg()] to find
1d070 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20   the text.** of 
1d080 74 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f  the parsing erro
1d090 72 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69  r that results i
1d0a0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  n an [SQLITE_SCH
1d0b0 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20  EMA] return..** 
1d0c0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1d0d0 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
1d0e0 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
1d0f0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1d100 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
1d110 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
1d120 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
1d130 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
1d140 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
1d150 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
1d160 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
1d170 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
1d180 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
1d190 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
1d1a0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
1d1b0 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
1d1c0 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
1d1d0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
1d1e0 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
1d1f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
1d200 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
1d210 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
1d220 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
1d230 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
1d240 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
1d250 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1d260 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
1d270 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
1d280 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1d290 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
1d2a0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1d2b0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f   ^If the value o
1d2c0 66 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20 7c  f a [parameter |
1d2d0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
1d2e0 20 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c   in the WHERE cl
1d2f0 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68  ause might.** ch
1d300 61 6e 67 65 20 74 68 65 20 71 75 65 72 79 20 70  ange the query p
1d310 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
1d320 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74  ent, then the st
1d330 61 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a  atement may be.*
1d340 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1d350 72 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 69  recompiled (as i
1d360 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
1d370 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1d380 29 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 0a  ) on the first .
1d390 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1d3a0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
1d3b0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74 6f  ng any change to
1d3c0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
1d3d0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
1d3e0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b  ndings] of the [
1d3f0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
1d400 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
1d410 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
1d420 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
1d430 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1d440 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1d450 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1d460 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1d470 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1d480 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1d490 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1d4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1d4b0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1d4c0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1d4d0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1d4e0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1d4f0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1d500 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1d510 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1d520 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1d530 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1d540 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1d550 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1d560 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
1d570 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1d580 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1d590 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1d5a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1d5b0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1d5c0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1d5d0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1d5e0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1d5f0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1d600 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1d610 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1d620 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1d630 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1d640 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1d650 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1d660 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1d670 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1d680 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1d690 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1d6a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d6b0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d6c0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1d6d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1d6e0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1d6f0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1d700 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1d710 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1d720 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1d730 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1d740 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1d750 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1d760 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1d770 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1d780 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1d790 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1d7a0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1d7b0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1d7c0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1d7d0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1d7e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1d7f0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
1d800 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1d810 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1d820 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1d830 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1d840 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1d850 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1d860 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1d870 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1d880 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1d890 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1d8a0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1d8b0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1d8c0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1d8d0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1d8e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1d8f0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1d900 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1d910 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1d920 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
1d930 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
1d940 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
1d950 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
1d960 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1d970 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
1d980 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
1d990 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
1d9a0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
1d9b0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
1d9c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d9d0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
1d9e0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
1d9f0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
1da00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1da10 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1da20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1da30 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
1da40 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
1da50 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1da60 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1da70 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
1da80 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
1da90 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
1daa0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
1dab0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
1dac0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1dad0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
1dae0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
1daf0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1db00 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
1db10 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
1db20 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
1db30 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
1db40 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
1db50 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
1db60 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
1db70 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
1db80 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
1db90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1dba0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
1dbb0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
1dbc0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
1dbd0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
1dbe0 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
1dbf0 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
1dc00 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
1dc10 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
1dc20 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
1dc30 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
1dc40 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1dc50 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1dc60 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
1dc70 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1dc80 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
1dc90 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
1dca0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1dcb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1dcc0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
1dcd0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
1dce0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
1dcf0 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
1dd00 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
1dd10 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
1dd20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1dd30 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
1dd40 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
1dd50 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
1dd60 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
1dd70 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
1dd80 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
1dd90 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c  eld.  A internal
1dda0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1ddb0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
1ddc0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1ddd0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
1dde0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1ddf0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
1de00 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1de10 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
1de20 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
1de30 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
1de40 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
1de50 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1de60 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
1de70 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1de80 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1de90 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
1dea0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
1deb0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
1dec0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
1ded0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
1dee0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
1def0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
1df00 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
1df10 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
1df20 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
1df30 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1df40 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1df50 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1df60 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
1df70 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
1df80 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
1df90 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
1dfa0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
1dfb0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
1dfc0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
1dfd0 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
1dfe0 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
1dff0 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65  on between betwe
1e000 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1e010 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1e020 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e030 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
1e040 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
1e050 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
1e060 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1e070 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
1e080 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
1e090 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
1e0a0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1e0b0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
1e0c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1e0d0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
1e0e0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
1e0f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e100 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
1e110 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
1e120 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
1e130 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
1e140 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1e150 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e160 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
1e170 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
1e180 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
1e190 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e1a0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
1e1b0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
1e1c0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
1e1d0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
1e1e0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
1e1f0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
1e200 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
1e210 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e220 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
1e230 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
1e240 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
1e250 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
1e260 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
1e270 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
1e280 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
1e290 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
1e2a0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
1e2b0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
1e2c0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
1e2d0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
1e2e0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
1e2f0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
1e300 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
1e310 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
1e320 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1e330 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1e340 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
1e350 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1e360 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
1e370 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
1e380 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
1e390 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
1e3a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1e3b0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
1e3c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
1e3d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
1e3e0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
1e3f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
1e400 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
1e410 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
1e420 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
1e430 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
1e440 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
1e450 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
1e460 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
1e470 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1e480 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
1e490 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
1e4a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
1e4b0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
1e4c0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
1e4d0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
1e4e0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
1e4f0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1e500 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
1e510 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
1e520 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
1e530 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
1e540 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
1e550 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
1e560 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
1e570 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
1e580 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
1e590 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1e5a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
1e5b0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
1e5c0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
1e5d0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
1e5e0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
1e5f0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
1e600 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
1e610 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
1e620 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
1e630 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
1e640 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
1e650 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
1e660 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
1e670 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
1e680 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
1e690 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
1e6a0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
1e6b0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
1e6c0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e  meric identifer.
1e6d0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
1e6e0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
1e6f0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
1e700 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
1e710 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
1e720 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
1e730 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
1e740 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1e750 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1e760 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
1e770 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1e780 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1e790 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1e7a0 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
1e7b0 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
1e7c0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
1e7d0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
1e7e0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
1e7f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e800 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
1e810 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
1e820 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1e830 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
1e840 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
1e850 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
1e860 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
1e870 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
1e880 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
1e890 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
1e8a0 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
1e8b0 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
1e8c0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
1e8d0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
1e8e0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
1e8f0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
1e900 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
1e910 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
1e920 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
1e930 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
1e940 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
1e950 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
1e960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1e970 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1e980 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
1e990 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
1e9a0 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
1e9b0 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
1e9c0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
1e9d0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
1e9e0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1e9f0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
1ea00 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
1ea10 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
1ea20 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
1ea30 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
1ea40 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
1ea50 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
1ea60 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
1ea70 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
1ea80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1ea90 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
1eaa0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
1eab0 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
1eac0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
1ead0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1eae0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1eaf0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
1eb00 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
1eb10 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
1eb20 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
1eb30 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
1eb40 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
1eb50 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1eb60 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
1eb70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1eb80 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
1eb90 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
1eba0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
1ebb0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1ebc0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
1ebd0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1ebe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
1ebf0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
1ec00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
1ec10 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ), sqlite3_bind_
1ec20 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73  text(), and.** s
1ec30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1ec40 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75  16() is a destru
1ec50 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
1ec60 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
1ec70 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
1ec80 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
1ec90 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
1eca0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
1ecb0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
1ecc0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
1ecd0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
1ece0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
1ecf0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
1ed00 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
1ed10 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
1ed20 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
1ed30 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
1ed40 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
1ed50 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1ed60 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
1ed70 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
1ed80 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
1ed90 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
1eda0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
1edb0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
1edc0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
1edd0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
1ede0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
1edf0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1ee00 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1ee10 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
1ee20 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
1ee30 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
1ee40 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
1ee50 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
1ee60 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
1ee70 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
1ee80 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
1ee90 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
1eea0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
1eeb0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
1eec0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
1eed0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
1eee0 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
1eef0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
1ef00 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
1ef10 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
1ef20 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
1ef30 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
1ef40 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
1ef50 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
1ef60 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
1ef70 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
1ef80 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
1ef90 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
1efa0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
1efb0 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
1efc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
1efd0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
1efe0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
1eff0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
1f000 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1f010 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
1f020 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
1f030 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
1f040 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1f050 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
1f060 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
1f070 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
1f080 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
1f090 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
1f0a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1f0b0 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
1f0c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
1f0d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
1f0e0 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
1f0f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1f100 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
1f110 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
1f120 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
1f130 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
1f140 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
1f150 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
1f160 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
1f170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1f180 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
1f190 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
1f1a0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
1f1b0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
1f1c0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
1f1d0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
1f1e0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
1f1f0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
1f200 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
1f210 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
1f220 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
1f230 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
1f240 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
1f250 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
1f260 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1f270 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
1f280 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
1f290 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
1f2a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1f2b0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1f2c0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1f2d0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f2e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1f2f0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
1f300 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f310 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
1f320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f330 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
1f340 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1f350 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
1f360 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1f370 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f380 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1f390 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
1f3a0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
1f3b0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
1f3c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1f3d0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1f3e0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
1f3f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
1f400 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
1f410 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f420 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
1f430 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
1f440 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1f450 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1f460 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
1f470 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1f480 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1f490 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1f4a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1f4b0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1f4c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1f4d0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1f4e0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
1f4f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1f500 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
1f510 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1f520 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1f530 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1f540 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
1f550 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f560 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
1f570 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
1f580 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
1f590 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
1f5a0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
1f5b0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
1f5c0 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
1f5d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
1f5e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
1f5f0 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
1f600 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
1f610 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
1f620 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
1f630 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
1f640 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
1f650 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
1f660 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1f670 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
1f680 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1f690 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
1f6a0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
1f6b0 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
1f6c0 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
1f6d0 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
1f6e0 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
1f6f0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
1f700 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
1f710 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
1f720 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
1f730 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1f740 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
1f750 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
1f760 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
1f770 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
1f780 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
1f790 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
1f7a0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1f7b0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1f7c0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1f7d0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1f7e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f7f0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
1f800 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f810 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1f820 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1f830 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f840 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
1f850 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
1f860 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
1f870 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
1f880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1f890 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f8a0 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
1f8b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
1f8c0 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
1f8d0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
1f8e0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
1f8f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f900 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
1f910 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1f920 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
1f930 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1f940 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
1f950 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
1f960 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
1f970 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1f980 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1f990 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
1f9a0 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
1f9b0 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
1f9c0 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
1f9d0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
1f9e0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
1f9f0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
1fa00 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
1fa10 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
1fa20 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
1fa30 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
1fa40 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
1fa50 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
1fa60 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
1fa70 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
1fa80 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
1fa90 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
1faa0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1fab0 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
1fac0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
1fad0 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
1fae0 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
1faf0 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
1fb00 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
1fb10 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
1fb20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
1fb30 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
1fb40 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
1fb50 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
1fb60 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
1fb70 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
1fb80 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
1fb90 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
1fba0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
1fbb0 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
1fbc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fbd0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1fbe0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1fbf0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1fc00 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1fc10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1fc20 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1fc30 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1fc40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1fc50 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
1fc60 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1fc70 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1fc80 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
1fc90 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
1fca0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
1fcb0 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
1fcc0 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
1fcd0 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
1fce0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
1fcf0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
1fd00 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
1fd10 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
1fd20 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
1fd30 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
1fd40 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
1fd50 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1fd60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1fd70 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1fd80 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
1fd90 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
1fda0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
1fdb0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
1fdc0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
1fdd0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
1fde0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
1fdf0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
1fe00 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
1fe10 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
1fe20 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
1fe30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1fe40 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
1fe50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1fe60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1fe70 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1fe80 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1fe90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1fea0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
1feb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1fec0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1fed0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1fee0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1fef0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
1ff00 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
1ff10 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
1ff20 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
1ff30 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
1ff40 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
1ff50 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
1ff60 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
1ff70 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
1ff80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
1ff90 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
1ffa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
1ffb0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
1ffc0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
1ffd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
1ffe0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
1fff0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
20000 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
20010 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
20020 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
20030 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
20040 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
20050 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
20060 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
20070 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
20080 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
20090 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
200a0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
200b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
200c0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
200d0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
200e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
200f0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
20100 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
20110 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
20120 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
20130 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
20140 41 54 45 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ATE])..*/.int sq
20150 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
20160 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
20170 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
20180 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
20190 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
201a0 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
201b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
201c0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
201d0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
201e0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
201f0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
20200 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
20210 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
20220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20230 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
20240 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
20250 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
20260 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
20270 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
20280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
20290 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
202a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
202b0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
202c0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
202d0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
202e0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
202f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20300 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
20310 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
20320 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
20330 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
20340 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
20350 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
20360 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
20370 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
20380 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
20390 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
203a0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
203b0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
203c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
203d0 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
203e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
203f0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
20400 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
20410 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
20420 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
20430 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
20440 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
20450 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
20460 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
20470 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
20480 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
20490 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
204a0 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
204b0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
204c0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
204d0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
204e0 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
204f0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
20500 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
20510 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
20520 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
20530 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
20540 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
20550 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
20560 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
20570 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
20580 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
20590 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
205a0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
205b0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
205c0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
205d0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
205e0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
205f0 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
20600 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
20610 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
20620 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
20630 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
20640 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
20650 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20660 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
20670 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
20680 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
20690 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
206a0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
206b0 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
206c0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
206d0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
206e0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
206f0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
20700 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
20710 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
20720 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
20730 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
20740 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
20750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
20760 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
20770 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
20780 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
20790 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
207a0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
207b0 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
207c0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
207d0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
207e0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
207f0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
20800 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
20810 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
20820 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
20830 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
20840 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
20850 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
20860 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
20870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
20880 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
20890 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
208a0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
208b0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
208c0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
208d0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
208e0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
208f0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
20900 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
20910 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
20920 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
20930 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
20940 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
20950 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
20960 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
20970 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
20980 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
20990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
209a0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
209b0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
209c0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
209d0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
209e0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
209f0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
20a00 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
20a10 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
20a20 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
20a30 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
20a40 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
20a50 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
20a60 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
20a70 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
20a80 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
20a90 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
20aa0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
20ab0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
20ac0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
20ad0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
20ae0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
20af0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
20b00 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
20b10 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
20b20 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
20b30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
20b40 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
20b50 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
20b60 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
20b70 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
20b80 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
20b90 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
20ba0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
20bb0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
20bc0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
20bd0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
20be0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
20bf0 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
20c00 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
20c10 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
20c20 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
20c30 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
20c40 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
20c50 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
20c60 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
20c70 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
20c80 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
20c90 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
20ca0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
20cb0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
20cc0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
20cd0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
20ce0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
20cf0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
20d00 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
20d10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
20d20 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
20d30 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
20d40 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
20d50 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
20d60 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
20d70 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
20d80 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
20d90 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
20da0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
20db0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
20dc0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
20dd0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
20de0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
20df0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
20e00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20e10 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
20e20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
20e30 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
20e40 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
20e50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
20e60 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
20e70 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
20e80 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
20e90 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
20ea0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
20eb0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
20ec0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
20ed0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
20ee0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
20ef0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
20f00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
20f10 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
20f20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
20f30 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
20f40 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20f50 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20f60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
20f70 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
20f80 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
20f90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
20fa0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
20fb0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
20fc0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
20fd0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
20fe0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
20ff0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
21000 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70  ** ^(The first p
21010 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
21020 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21030 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
21040 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
21050 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
21060 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
21070 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
21080 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
21090 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
210a0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
210b0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
210c0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
210d0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
210e0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
210f0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
21100 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
21110 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74  d.)^  ^If the Nt
21120 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  h column of the 
21130 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e  result set is an
21140 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
21150 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e  r subquery, then
21160 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
21180 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
21190 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55  ring is always U
211a0 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a  TF-8 encoded..**
211b0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
211c0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
211d0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
211e0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
211f0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
21200 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
21210 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
21220 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
21230 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
21240 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
21250 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
21260 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
21270 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
21280 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
21290 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
212a0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
212b0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
212c0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
212d0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
212e0 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  (i==0).)^.**.** 
212f0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e  ^SQLite uses dyn
21300 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79  amic run-time ty
21310 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20  ping.  ^So just 
21320 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e  because a column
21330 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20  .** is declared 
21340 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72  to contain a par
21350 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65  ticular type doe
21360 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20  s not mean that 
21370 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72  the.** data stor
21380 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d  ed in that colum
21390 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c  n is of the decl
213a0 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69  ared type.  SQLi
213b0 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c  te is.** strongl
213c0 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65  y typed, but the
213d0 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d   typing is dynam
213e0 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20  ic not static.  
213f0 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f  ^Type.** is asso
21400 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69  ciated with indi
21410 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e  vidual values, n
21420 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74  ot with the cont
21430 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74  ainers.** used t
21440 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c  o hold those val
21450 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ues..*/.const ch
21460 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
21470 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
21480 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
21490 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
214a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
214b0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
214c0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
214d0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
214e0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
214f0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
21500 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21510 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
21520 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
21530 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
21540 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21550 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
21560 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
21570 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
21580 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
21590 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
215a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
215b0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
215c0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
215d0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
215e0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
215f0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
21600 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
21610 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
21620 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
21630 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
21640 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
21650 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
21660 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
21670 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
21680 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
21690 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
216a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
216b0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
216c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
216d0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
216e0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
216f0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
21700 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
21710 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
21720 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
21730 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
21740 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
21750 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
21760 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
21770 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
21780 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
21790 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
217a0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
217b0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
217c0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
217d0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
217e0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
217f0 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
21800 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
21810 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
21820 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
21830 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
21840 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
21850 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
21860 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
21870 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
21880 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
21890 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
218a0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
218b0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
218c0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
218d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
218e0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
218f0 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
21900 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
21910 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
21920 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
21930 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
21940 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
21950 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
21960 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
21970 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
21980 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
21990 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
219a0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
219b0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
219c0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
219d0 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
219e0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
219f0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
21a00 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
21a10 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
21a20 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
21a30 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
21a40 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
21a50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
21a60 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
21a70 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
21a80 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
21a90 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
21aa0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
21ab0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
21ac0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
21ad0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
21ae0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21af0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
21b00 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
21b10 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
21b20 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
21b30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
21b40 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
21b50 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
21b60 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
21b70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
21b80 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
21b90 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
21ba0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
21bb0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
21bc0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
21bd0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
21be0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
21bf0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
21c00 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
21c10 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
21c20 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
21c30 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
21c40 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
21c50 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
21c60 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
21c70 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
21c80 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
21c90 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
21ca0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
21cb0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
21cc0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
21cd0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
21ce0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
21cf0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
21d00 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
21d10 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
21d20 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
21d30 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
21d40 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
21d50 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
21d60 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
21d70 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
21d80 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
21d90 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
21da0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
21db0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
21dc0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
21dd0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
21de0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21df0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
21e00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
21e10 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
21e20 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
21e30 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
21e40 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
21e50 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
21e60 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
21e70 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
21e80 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
21e90 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
21ea0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
21eb0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
21ec0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
21ed0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
21ee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21ef0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
21f00 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
21f10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
21f20 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
21f30 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
21f40 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
21f50 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
21f60 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
21f70 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
21f80 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
21f90 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
21fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21fb0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
21fc0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
21fd0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
21fe0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
21ff0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
22000 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
22010 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
22020 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
22030 32 33 2e 31 2c 20 69 74 20 77 61 73 20 72 65 71  23.1, it was req
22040 75 69 72 65 64 0a 2a 2a 20 61 66 74 65 72 20 73  uired.** after s
22050 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65  qlite3_step() re
22060 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 20  turned anything 
22070 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
22080 54 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20  TE_ROW] that.** 
22090 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
220a0 5d 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  ] be called befo
220b0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
220c0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
220d0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
220e0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 69  ).  Failure to i
220f0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72  nvoke [sqlite3_r
22100 65 73 65 74 28 29 5d 20 69 6e 20 74 68 69 73 20  eset()] in this 
22110 77 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73  way would.** res
22120 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  ult in an [SQLIT
22130 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e  E_MISUSE] return
22140 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74   from sqlite3_st
22150 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
22160 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  .** version 3.6.
22170 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74  23.1, sqlite3_st
22180 65 70 28 29 20 62 65 67 61 6e 20 63 61 6c 6c 69  ep() began calli
22190 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
221a0 74 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74  t()] .** automat
221b0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
221c0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
221d0 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e  er than returnin
221e0 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  g [SQLITE_MISUSE
221f0 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ].  .**.** <b>Go
22200 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
22210 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
22220 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
22230 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
22240 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
22250 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
22260 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
22270 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
22280 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
22290 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
222a0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
222b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
222c0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
222d0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
222e0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
222f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22300 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
22310 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
22320 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
22330 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
22340 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
22350 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
22360 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
22370 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
22380 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
22390 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
223a0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
223b0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
223c0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
223d0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
223e0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
223f0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
22400 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
22410 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
22420 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
22430 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
22440 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22450 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
22460 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
22470 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
22480 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
22490 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
224a0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
224b0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
224c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
224d0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
224e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
224f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
22500 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65  .int sqlite3_ste
22510 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
22520 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22530 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
22540 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
22550 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20   set.**.** ^The 
22560 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
22570 6e 74 28 50 29 20 74 68 65 20 6e 75 6d 62 65 72  nt(P) the number
22580 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
22590 68 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  he.** of the res
225a0 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
225b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
225c0 50 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  P..*/.int sqlite
225d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
225e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
225f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
22600 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
22610 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
22620 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
22630 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
22640 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
22650 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
22660 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
22670 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
22680 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
22690 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
226a0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
226b0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
226c0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
226d0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
226e0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
226f0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
22700 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
22710 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
22720 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
22730 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
22740 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
22750 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
22760 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
22770 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
22780 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
22790 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
227a0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
227b0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
227c0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
227d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
227e0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
227f0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
22800 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
22810 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
22820 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
22830 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
22840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
22850 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
22860 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
22870 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
22880 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
22890 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
228a0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
228b0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
228c0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
228d0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
228e0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
228f0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
22900 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
22910 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
22920 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
22930 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
22940 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
22950 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
22960 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
22970 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
22980 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
22990 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
229a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
229b0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
229c0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
229d0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
229e0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
229f0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
22a00 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
22a10 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
22a20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
22a30 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
22a40 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
22a50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
22a60 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
22a70 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
22a80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22a90 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
22aa0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
22ab0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
22ac0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
22ad0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
22ae0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
22af0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
22b00 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
22b10 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
22b20 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
22b30 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
22b40 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
22b50 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
22b60 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
22b70 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
22b80 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
22b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
22ba0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
22bb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22bc0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
22bd0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
22be0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
22bf0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
22c00 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
22c10 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
22c20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
22c30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
22c40 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
22c50 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
22c60 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
22c70 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
22c80 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
22c90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
22ca0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
22cb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
22cc0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
22cd0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
22ce0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
22cf0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
22d00 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
22d10 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
22d20 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
22d30 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
22d40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
22d50 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
22d60 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
22d70 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
22d80 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
22d90 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
22da0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
22db0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
22dc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
22dd0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
22de0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
22df0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
22e00 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
22e10 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
22e20 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
22e30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
22e40 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
22e50 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
22e60 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
22e70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22e80 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
22e90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
22ea0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
22eb0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
22ec0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
22ed0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
22ee0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
22ef0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
22f00 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
22f10 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
22f20 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
22f30 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
22f40 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
22f50 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
22f60 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
22f70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
22f80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
22f90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
22fa0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
22fb0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
22fc0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
22fd0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
22fe0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
22ff0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
23000 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
23010 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
23020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23030 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
23040 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
23050 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23060 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
23070 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
23080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
23090 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
230a0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
230b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
230c0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
230d0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
230e0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
230f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23100 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
23110 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
23120 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
23130 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
23140 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
23150 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
23160 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
23170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23180 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
23190 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
231a0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
231b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
231c0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
231d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
231e0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
231f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
23200 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
23210 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
23220 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
23230 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
23240 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
23250 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
23260 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
23270 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
23280 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
23290 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
232a0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
232b0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
232c0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
232d0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
232e0 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
232f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
23300 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
23310 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
23320 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
23330 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
23340 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
23350 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
23360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23370 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
23380 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
23390 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
233a0 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
233b0 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  ays zero termina
233c0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
233d0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
233e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
233f0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
23400 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
23410 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  an arbitrary.** 
23420 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c  pointer, possibl
23430 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  y even a NULL po
23440 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
23450 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
23460 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69  _bytes16() routi
23470 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
23480 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23490 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c  bytes().** but l
234a0 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74  eaves the result
234b0 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   in UTF-16 in na
234c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
234d0 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
234e0 2e 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74  ..** ^The zero t
234f0 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
23500 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
23510 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  s count..**.** ^
23520 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
23530 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
23540 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
23550 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
23560 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
23570 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
23580 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
23590 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
235a0 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
235b0 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
235c0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
235d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
235e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
235f0 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
23600 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
23610 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
23620 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
23630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
23640 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
23650 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
23660 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
23670 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
23680 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
23690 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
236a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
236b0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
236c0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
236d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
236e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
236f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
23700 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
23710 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
23720 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
23730 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
23740 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
23750 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
23760 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
23770 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
23780 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
23790 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
237a0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
237b0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
237c0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
237d0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
237e0 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
237f0 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
23800 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
23810 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
23820 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
23830 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
23840 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
23850 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
23860 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
23870 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
23880 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
23890 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
238a0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
238b0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
238c0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
238d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
238e0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
238f0 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
23900 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
23910 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
23920 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
23930 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
23940 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
23950 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
23960 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
23970 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
23980 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
23990 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
239a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
239b0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
239c0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
239d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
239e0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
239f0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
23a00 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
23a10 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
23a20 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
23a30 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
23a40 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
23a50 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
23a60 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
23a70 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
23a80 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
23a90 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
23aa0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
23ab0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
23ac0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
23ad0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
23ae0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
23af0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
23b00 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
23b10 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
23b20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
23b30 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
23b40 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
23b50 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
23b60 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
23b70 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
23b80 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
23b90 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
23ba0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
23bb0 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
23bc0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
23bd0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
23be0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
23bf0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
23c00 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
23c10 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
23c20 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
23c30 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
23c40 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
23c50 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
23c60 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
23c70 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
23c80 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
23c90 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
23ca0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
23cb0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
23cc0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
23cd0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
23ce0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
23cf0 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
23d00 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
23d10 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
23d20 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
23d30 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
23d40 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
23d50 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
23d60 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
23d70 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
23d80 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
23d90 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
23da0 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
23db0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
23dc0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
23dd0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
23de0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rammers..**.** ^
23df0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
23e00 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
23e10 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
23e20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
23e30 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
23e40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
23e50 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
23e60 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
23e70 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
23e80 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
23e90 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
23ea0 2e 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76  ..** ^(Type conv
23eb0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
23ec0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
23ed0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
23ee0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
23ef0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
23f00 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
23f10 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
23f20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
23f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23f40 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
23f50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
23f60 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
23f70 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
23f80 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
23f90 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
23fa0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
23fb0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
23fc0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
23fd0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
23fe0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
23ff0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
24000 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
24010 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
24020 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
24030 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
24040 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
24050 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
24060 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
24070 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
24080 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
24090 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
240a0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
240b0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
240c0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
240d0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
240e0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
240f0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
24100 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
24110 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f  /ul>)^.**.** ^Co
24120 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
24130 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
24140 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
24150 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
24160 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
24170 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
24180 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
24190 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
241a0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
241b0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
241c0 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
241d0 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68  points to will h
241e0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
241f0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
24200 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
24210 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
24220 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
24230 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
24240 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
24250 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
24260 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
24270 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
24280 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
24290 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61  ..**.** ^(The sa
242a0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
242b0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
242c0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
242d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
242e0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
242f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
24300 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
24310 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
24320 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
24330 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
24340 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
24350 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
24360 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
24370 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
24380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24390 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
243a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
243b0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
243c0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
243d0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
243e0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  >.** </ul>)^.**.
243f0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
24400 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
24410 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
24420 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
24430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
24440 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
24450 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
24460 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
24470 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
24480 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
24490 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
244a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
244b0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
244c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
244d0 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
244e0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
244f0 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
24500 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
24510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24520 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
24530 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
24540 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
24550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24560 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
24570 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
24580 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24590 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
245a0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
245b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
245c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
245d0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
245e0 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
245f0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
24600 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
24610 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
24620 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
24630 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
24640 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
24650 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
24660 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
24670 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
24680 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
24690 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
246a0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
246b0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
246c0 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
246d0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
246e0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
246f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
24700 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
24710 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
24720 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
24730 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
24740 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
24750 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
24760 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
24770 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
24780 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
24790 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
247a0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
247b0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
247c0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
247d0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
247e0 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
247f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
24800 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
24810 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
24820 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
24830 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
24840 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
24850 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
24860 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
24870 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24880 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
24890 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
248a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
248b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
248c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
248d0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
248e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
248f0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
24900 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
24910 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
24920 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
24930 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24940 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
24950 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
24960 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24970 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
24980 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
24990 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
249a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
249b0 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
249c0 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
249d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
249e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
249f0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
24a00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24a10 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
24a20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24a30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24a40 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
24a50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24a60 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
24a70 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
24a80 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
24a90 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24aa0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24ab0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
24ac0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
24ad0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
24ae0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
24af0 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
24b00 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
24b10 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
24b20 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
24b30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
24b40 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63  as executed succ
24b50 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20  essfully or not 
24b60 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
24b70 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f   then.** SQLITE_
24b80 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
24b90 5e 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  ^If execution of
24ba0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
24bb0 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a  ailed then an.**
24bc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
24bd0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
24be0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
24bf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ed..**.** ^This 
24c00 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
24c10 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
24c20 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
24c30 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
24c40 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24c50 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65  ement].  ^If the
24c60 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
24c70 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70   has not.** comp
24c80 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20  leted execution 
24c90 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  when this routin
24ca0 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61  e is called, tha
24cb0 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63  t is like.** enc
24cc0 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72  ountering an err
24cd0 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  or or an [sqlite
24ce0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
24cf0 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e  terrupt]..** ^In
24d00 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73  complete updates
24d10 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62   may be rolled b
24d20 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74  ack and transact
24d30 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a  ions canceled,.*
24d40 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
24d50 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
24d60 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72  , and the.** [er
24d70 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
24d80 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
24d90 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e  TE_ABORT]..*/.in
24da0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
24db0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
24dc0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
24dd0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
24de0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
24df0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
24e00 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
24e10 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
24e20 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
24e30 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
24e40 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
24e50 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
24e60 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
24e70 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
24e80 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
24e90 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
24ea0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
24eb0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
24ec0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
24ed0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
24ee0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
24ef0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
24f00 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
24f10 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
24f20 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
24f30 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
24f40 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
24f50 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
24f60 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
24f70 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
24f80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24f90 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
24fa0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
24fb0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
24fc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
24fd0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
24fe0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
24ff0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
25000 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25010 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
25020 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
25030 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
25040 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
25050 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
25060 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
25070 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
25080 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
25090 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
250a0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
250b0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
250c0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
250d0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
250e0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
250f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25100 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
25110 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
25120 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
25130 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
25140 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
25150 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
25160 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25170 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
25180 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
25190 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
251a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
251b0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
251c0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
251d0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
251e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
251f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
25200 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
25210 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
25220 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
25230 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
25240 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
25250 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
25260 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
25270 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
25280 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
25290 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
252a0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
252b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
252c0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
252d0 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  e two functions 
252e0 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
252f0 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
25300 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
25310 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
25320 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
25330 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
25340 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
25350 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
25360 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
25370 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
25380 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
25390 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
253a0 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20   between the.** 
253b0 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20  two is that the 
253c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
253d0 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
253e0 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74  e (scalar) funct
253f0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
25400 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20  ate, is encoded 
25410 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c  in UTF-8 for sql
25420 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25430 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31  tion() and UTF-1
25440 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  6.** for sqlite3
25450 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25460 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  16()..**.** ^The
25470 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
25480 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
25490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
254a0 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
254b0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
254c0 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
254d0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
254e0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
254f0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
25500 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
25510 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25520 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
25530 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
25540 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
25550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
25560 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54  arately..**.** T
25570 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
25580 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
25590 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
255a0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
255b0 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
255c0 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
255d0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
255e0 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
255f0 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
25600 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65  f.** the zero-te
25610 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20  rminator.  Note 
25620 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65  that the name le
25630 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
25640 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63   bytes, not.** c
25650 68 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79  haracters.  ^Any
25660 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
25670 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
25680 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
25690 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
256a0 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  in [SQLITE_ERROR
256b0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
256c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
256d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
256e0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
256f0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
25700 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
25710 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
25720 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
25730 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
25740 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
25750 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
25760 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
25770 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
25780 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
25790 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
257a0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
257b0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
257c0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
257d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
257e0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
257f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
25800 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
25810 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
25820 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
25830 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
25840 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72  ..**.** The four
25850 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
25860 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
25870 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
25880 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
25890 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
258a0 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
258b0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
258c0 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51  ameters.  Any SQ
258d0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
258e0 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
258f0 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
25900 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54  .** work with UT
25910 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
25920 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
25930 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
25940 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
25950 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
25960 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
25970 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
25980 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
25990 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
259a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
259b0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
259c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
259d0 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
259e0 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
259f0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
25a00 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
25a10 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
25a20 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
25a30 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
25a40 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
25a50 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
25a60 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
25a70 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
25a80 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
25a90 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
25aa0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
25ab0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
25ac0 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
25ad0 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
25ae0 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
25af0 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
25b00 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
25b10 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
25b20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
25b30 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
25b40 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
25b50 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
25b60 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
25b70 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
25b80 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
25b90 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
25ba0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
25bb0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
25bc0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
25bd0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
25be0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ()].)^.**.** The
25bf0 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68   seventh, eighth
25c00 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d   and ninth param
25c10 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
25c20 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
25c30 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
25c40 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
25c50 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
25c60 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
25c70 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
25c80 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
25c90 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
25ca0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
25cb0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
25cc0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
25cd0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
25ce0 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
25cf0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
25d00 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
25d10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
25d20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51  ^An aggregate SQ
25d30 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
25d40 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
25d50 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a  ation of xStep.*
25d60 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64  * and xFinal and
25d70 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20   NULL should be 
25d80 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
25d90 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
25da0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
25db0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
25dc0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
25dd0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
25de0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
25df0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  s..**.** ^It is 
25e00 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
25e10 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
25e20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
25e30 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
25e40 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
25e50 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
25e60 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
25e70 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
25e80 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
25e90 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
25ea0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
25eb0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
25ec0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
25ed0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
25ee0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
25ef0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
25f00 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
25f10 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
25f20 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
25f30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25f40 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
25f50 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
25f60 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
25f70 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
25f80 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
25f90 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
25fa0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
25fb0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
25fc0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
25fd0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
25fe0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
25ff0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
26000 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
26010 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
26020 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
26030 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
26040 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
26050 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
26060 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
26070 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
26080 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
26090 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
260a0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
260b0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
260c0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
260d0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
260e0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
260f0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
26100 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
26110 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
26120 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
26130 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26140 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66  tions..** ^The f
26150 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  irst application
26160 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26170 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e  n with a given n
26180 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c  ame overrides al
26190 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75  l.** built-in fu
261a0 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73  nctions in the s
261b0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
261c0 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74  nnection] with t
261d0 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
261e0 20 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70   ^Subsequent app
261f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26200 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68   functions of th
26210 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79  e same name only
26220 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72   override .** pr
26230 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ior application-
26240 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26250 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78  s that are an ex
26260 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68  act match for th
26270 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70  e.** number of p
26280 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72  arameters and pr
26290 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67  eferred encoding
262a0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
262b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
262c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
262d0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
262e0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
262f0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
26300 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
26310 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
26320 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
26330 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
26340 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
26350 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
26360 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
26370 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
26380 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
26390 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
263a0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
263b0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
263c0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
263d0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
263e0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
263f0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
26400 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
26410 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26420 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
26430 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
26440 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
26450 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
26460 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
26470 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
26480 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26490 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
264a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
264b0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
264c0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
264d0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
264e0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
264f0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
26500 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
26510 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
26520 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
26530 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
26540 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
26550 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
26560 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
26570 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
26580 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
26590 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f  _context*).);../
265a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
265b0 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
265c0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
265d0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
265e0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
265f0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
26600 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
26610 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
26620 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
26630 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
26640 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
26650 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
26660 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
26670 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
26680 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
26690 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
266a0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
266b0 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
266c0 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
266d0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
266e0 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
266f0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
26700 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
26710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
26720 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
26730 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
26740 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
26750 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
26760 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
26770 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
26780 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
26790 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
267a0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
267b0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
267c0 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
267d0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
267e0 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
267f0 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
26800 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
26810 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
26820 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
26830 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
26840 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
26850 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
26860 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
26870 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
26880 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
26890 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
268a0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
268b0 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
268c0 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
268d0 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
268e0 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
268f0 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
26900 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
26910 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
26920 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
26930 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
26940 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
26950 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
26960 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
26970 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
26980 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
26990 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
269a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
269b0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
269c0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
269d0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
269e0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
269f0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
26a00 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
26a10 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
26a20 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
26a30 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
26a40 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
26a50 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
26a60 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
26a70 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
26a80 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
26a90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
26aa0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
26ab0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
26ac0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
26ad0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
26ae0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
26af0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
26b00 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
26b10 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
26b20 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
26b30 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
26b40 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
26b50 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
26b60 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
26b70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
26b80 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
26b90 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
26ba0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
26bb0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
26bc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
26bd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
26be0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
26bf0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
26c00 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
26c10 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
26c20 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
26c30 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
26c40 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
26c50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
26c60 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
26c70 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
26c80 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
26c90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
26ca0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
26cb0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
26cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26cd0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
26ce0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
26cf0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
26d00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26d10 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
26d20 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
26d30 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
26d40 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
26d50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
26d60 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
26d70 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
26d80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26d90 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
26da0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
26db0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
26dc0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
26dd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
26de0 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
26df0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
26e00 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
26e10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
26e20 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
26e30 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
26e40 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
26e50 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
26e60 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
26e70 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
26e80 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
26e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
26ea0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
26eb0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
26ec0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
26ed0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
26ee0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
26ef0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
26f00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26f10 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
26f20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
26f30 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
26f40 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
26f50 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
26f60 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
26f70 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
26f80 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
26f90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
26fa0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
26fb0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
26fc0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
26fd0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
26fe0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
26ff0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
27000 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
27010 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
27020 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
27030 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
27040 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
27050 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
27060 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
27070 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
27080 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
27090 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
270a0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
270b0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
270c0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
270d0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
270e0 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
270f0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
27100 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
27110 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
27120 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
27130 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
27140 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
27150 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
27160 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
27170 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
27180 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
27190 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
271a0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
271b0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
271c0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
271d0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
271e0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
271f0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
27200 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
27210 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
27220 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
27230 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
27240 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27250 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
27260 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27270 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
27280 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
27290 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
272a0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
272b0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
272c0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
272d0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
272e0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
272f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
27300 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
27310 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
27320 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
27330 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
27340 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
27350 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
27360 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
27370 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
27380 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
27390 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
273a0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
273b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
273c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
273d0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
273e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
273f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
27400 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
27410 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
27420 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
27430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27440 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
27450 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
27460 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
27470 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
27480 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
27490 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
274a0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
274b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
274c0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
274d0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
274e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
274f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
27500 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
27510 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
27520 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
27530 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
27540 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
27550 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
27560 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
27570 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
27580 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
27590 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
275a0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
275b0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
275c0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
275d0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
275e0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
275f0 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
27600 6d 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20  mplementions of 
27610 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
27620 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
27630 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
27640 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
27650 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
27660 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
27670 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
27680 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
27690 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
276a0 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
276b0 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
276c0 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
276d0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
276e0 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
276f0 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
27700 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
27710 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
27720 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
27730 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
27740 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
27750 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
27760 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
27770 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27780 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
27790 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
277a0 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
277b0 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
277c0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
277d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
277e0 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
277f0 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
27800 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
27810 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
27820 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
27830 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
27840 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
27850 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
27860 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
27870 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
27880 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
27890 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
278a0 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
278b0 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
278c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
278d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
278e0 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
278f0 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
27900 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
27910 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
27920 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
27930 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
27940 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
27950 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
27960 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
27970 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
27980 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27990 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
279a0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
279b0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
279c0 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a  ointer if N is.*
279d0 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  * less than or e
279e0 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
279f0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
27a00 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72  cate error occur
27a10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
27a20 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61  mount of space a
27a30 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
27a40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27a50 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a  ntext(C,N) is.**
27a60 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74   determined by t
27a70 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f  he N parameter o
27a80 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66  n first successf
27a90 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69  ul call.  Changi
27aa0 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  ng the.** value 
27ab0 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65  of N in subseque
27ac0 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
27ad0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27ae0 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a  text() within.**
27af0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
27b00 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
27b10 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72  tance will not r
27b20 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  esize the memory
27b30 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29  .** allocation.)
27b40 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
27b50 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
27b60 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
27b70 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
27b80 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27b90 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
27ba0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
27bb0 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
27bc0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
27bd0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
27be0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
27bf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
27c00 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
27c10 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
27c20 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
27c30 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
27c40 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
27c50 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
27c60 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
27c70 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
27c80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
27c90 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
27ca0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
27cb0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
27cc0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
27cd0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
27ce0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
27cf0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
27d00 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
27d10 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
27d20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
27d30 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
27d40 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
27d50 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
27d60 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
27d70 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
27d80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27d90 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
27da0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
27db0 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
27dc0 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
27dd0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
27de0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
27df0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27e00 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
27e10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27e20 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
27e30 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
27e40 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
27e50 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
27e60 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
27e70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
27e80 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
27e90 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
27ea0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
27eb0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
27ec0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
27ed0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
27ee0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
27ef0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
27f00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
27f10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27f20 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
27f30 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
27f40 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
27f50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
27f60 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
27f70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27f80 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
27f90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
27fa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27fb0 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
27fc0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
27fd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
27fe0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
27ff0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
28000 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
28010 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
28020 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
28030 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
28040 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
28050 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
28060 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
28070 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
28080 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
28090 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
280a0 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
280b0 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
280c0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
280d0 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
280e0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
280f0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
28100 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
28110 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
28120 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
28130 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
28140 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
28150 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
28160 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
28170 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
28180 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
28190 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
281a0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
281b0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
281c0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
281d0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
281e0 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
281f0 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
28200 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
28210 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
28220 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
28230 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
28240 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
28250 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
28260 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
28270 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
28280 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
28290 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
282a0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
282b0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
282c0 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
282d0 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
282e0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
282f0 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
28300 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
28310 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
28320 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
28330 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
28340 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
28350 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
28360 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
28370 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
28380 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
28390 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
283a0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
283b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
283c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
283d0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
283e0 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  ated by the sqli
283f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
28400 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  ) function with 
28410 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
28420 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65  .** value to the
28430 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28440 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  ined function. ^
28450 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
28460 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
28470 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
28480 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
28490 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
284a0 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
284b0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
284c0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
284d0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
284e0 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
284f0 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
28500 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
28510 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
28520 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
28530 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
28540 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
28550 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65  erface saves the
28560 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69   metadata.** poi
28570 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33  nted to by its 3
28580 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  rd parameter as 
28590 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72  the metadata for
285a0 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67   the N-th.** arg
285b0 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70  ument of the app
285c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
285d0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73   function.  Subs
285e0 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
285f0 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
28600 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72  uxdata() might r
28610 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c  eturn this data,
28620 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f   if it has.** no
28630 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64  t been destroyed
28640 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e  ..** ^If it is n
28650 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
28660 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
28670 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
28680 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
28690 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
286a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
286b0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
286c0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
286d0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
286e0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
286f0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
28700 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
28710 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
28720 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
28730 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
28740 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
28750 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
28760 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
28770 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
28780 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
28790 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
287a0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e   at any time.  ^
287b0 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74  The only guarant
287c0 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68  ee is that.** th
287d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c  e destructor wil
287e0 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f  l be called befo
287f0 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  re the metadata 
28800 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a  is dropped..**.*
28810 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
28820 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
28830 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
28840 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
28850 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73  r.** expressions
28860 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61   that are consta
28870 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  nt at compile ti
28880 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65  me. This include
28890 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  s literal.** val
288a0 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
288b0 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ers].)^.**.** Th
288c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
288d0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
288e0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
288f0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
28900 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
28910 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
28920 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
28930 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
28940 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
28950 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
28960 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
28970 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
28980 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
28990 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
289a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
289b0 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
289c0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
289d0 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
289e0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
289f0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
28a00 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
28a10 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
28a20 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
28a30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
28a40 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
28a50 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
28a60 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
28a70 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
28a80 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
28a90 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
28aa0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
28ab0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
28ac0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
28ad0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
28ae0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
28af0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
28b00 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
28b10 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
28b20 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
28b30 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
28b40 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
28b50 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
28b60 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
28b70 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
28b80 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
28b90 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
28ba0 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
28bb0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
28bc0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
28bd0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
28be0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
28bf0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
28c00 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74  ompilers.  See t
28c10 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a  icket #2191..*/.
28c20 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
28c30 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
28c40 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a  r_type)(void*);.
28c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
28c60 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c  TATIC      ((sql
28c70 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
28c80 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20  type)0).#define 
28c90 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
28ca0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
28cb0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29  tructor_type)-1)
28cc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28cd0 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65  : Setting The Re
28ce0 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46  sult Of An SQL F
28cf0 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68  unction.**.** Th
28d00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
28d10 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75   used by the xFu
28d20 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  nc or xFinal cal
28d30 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69  lbacks that.** i
28d40 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e  mplement SQL fun
28d50 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
28d60 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b  gates.  See.** [
28d70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28d80 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
28d90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28da0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
28db0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
28dc0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
28dd0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
28de0 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68  s work very much
28df0 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d   like the [param
28e00 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61  eter binding] fa
28e10 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74  mily of.** funct
28e20 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e  ions used to bin
28e30 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74  d values to host
28e40 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70   parameters in p
28e50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28e60 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  ts..** Refer to 
28e70 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  the [SQL paramet
28e80 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  er] documentatio
28e90 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
28ea0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
28eb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28ec0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
28ed0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
28ee0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
28ef0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
28f00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28f10 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
28f20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
28f30 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
28f40 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
28f50 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
28f60 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
28f70 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
28f80 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
28f90 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
28fa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
28fb0 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  roblob() interfa
28fc0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
28fd0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
28fe0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28ff0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29000 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
29010 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79  g all zero.** by
29020 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
29030 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e  in size, where N
29040 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
29050 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
29060 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
29070 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
29080 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
29090 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
290a0 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
290b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
290c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
290d0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
290e0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
290f0 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
29100 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
29110 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29120 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
29130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29140 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
29150 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
29160 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
29170 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
29180 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
29190 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
291a0 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
291b0 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
291c0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
291d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
291e0 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
291f0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29200 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
29210 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
29220 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
29230 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
29240 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
29250 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
29260 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
29270 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
29280 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
29290 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
292a0 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
292b0 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
292c0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
292d0 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
292e0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
292f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
29300 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
29310 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
29320 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
29330 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
29340 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
29350 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
29360 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
29370 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
29380 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
29390 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
293a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
293b0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
293c0 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
293d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
293e0 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
293f0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
29400 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
29410 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
29420 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
29430 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
29440 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
29450 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
29460 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29470 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
29480 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29490 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
294a0 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
294b0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
294c0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
294d0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
294e0 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
294f0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
29500 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
29510 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
29520 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
29530 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
29540 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
29550 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29560 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
29570 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
29580 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
29590 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
295a0 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
295b0 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
295c0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
295d0 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
295e0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
295f0 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
29600 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
29610 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
29620 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
29630 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29640 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
29650 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
29660 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
29670 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29680 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67  e3_result_toobig
29690 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
296a0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
296b0 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20  row an error.** 
296c0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
296d0 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
296e0 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
296f0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
29700 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29710 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
29720 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
29730 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
29740 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
29750 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
29760 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
29770 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
29780 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29790 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
297a0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
297b0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
297c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
297d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
297e0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
297f0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
29800 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
29810 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
29820 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29830 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
29840 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
29850 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
29860 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
29870 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29880 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
29890 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
298a0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
298b0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
298c0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
298d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
298e0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
298f0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
29900 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
29910 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
29920 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29930 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
29940 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29950 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
29960 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29970 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
29980 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29990 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
299a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
299b0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
299c0 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
299d0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
299e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
299f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
29a00 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
29a10 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
29a20 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
29a30 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
29a40 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
29a50 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
29a60 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
29a70 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
29a80 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
29a90 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
29aa0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
29ab0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
29ac0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
29ad0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
29ae0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29af0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29b00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
29b10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
29b20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29b30 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
29b40 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
29b50 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
29b60 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
29b70 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
29b80 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
29b90 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
29ba0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
29bb0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
29bc0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
29bd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
29be0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
29bf0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
29c00 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
29c10 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
29c20 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
29c30 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
29c40 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
29c50 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
29c60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
29c70 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
29c80 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  ion result..** ^
29c90 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
29ca0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
29cb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
29cc0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
29cd0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
29ce0 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
29cf0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
29d00 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
29d10 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
29d20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
29d30 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
29d40 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
29d50 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
29d60 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
29d70 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
29d80 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
29d90 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
29da0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
29db0 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
29dc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29dd0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
29de0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
29df0 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
29e00 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
29e10 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
29e20 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
29e30 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
29e40 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
29e50 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
29e60 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
29e70 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
29e80 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
29e90 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
29ea0 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
29eb0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
29ec0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
29ed0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
29ee0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
29ef0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29f00 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
29f10 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
29f20 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
29f30 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
29f40 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
29f50 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
29f60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
29f70 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
29f80 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
29f90 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
29fa0 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
29fb0 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
29fc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29fd0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
29fe0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
29ff0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
2a000 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a010 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2a020 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
2a030 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2a040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a050 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
2a060 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2a070 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
2a080 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2a090 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
2a0a0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
2a0b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2a0c0 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
2a0d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2a0e0 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
2a0f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
2a100 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
2a110 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
2a120 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
2a130 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
2a140 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
2a150 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
2a160 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a170 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
2a180 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
2a190 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
2a1a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2a1b0 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
2a1c0 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
2a1d0 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
2a1e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a1f0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
2a200 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
2a210 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
2a220 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2a230 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
2a240 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
2a250 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
2a260 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
2a270 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
2a280 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2a290 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
2a2a0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2a2b0 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
2a2c0 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
2a2d0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2a2e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a2f0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
2a300 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2a310 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2a320 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
2a330 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a340 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
2a350 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
2a360 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
2a370 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
2a380 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a390 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2a3a0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2a3b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2a3c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a3d0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2a3e0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2a3f0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2a400 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
2a410 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2a420 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a430 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
2a440 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2a450 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a460 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
2a470 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2a480 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a490 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
2a4a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2a4b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a4c0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
2a4d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2a4e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
2a4f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a500 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
2a510 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2a520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2a530 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
2a540 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
2a550 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2a560 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2a570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a580 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
2a590 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2a5a0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
2a5b0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2a5c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a5d0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
2a5e0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2a5f0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2a600 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2a610 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2a620 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
2a630 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2a640 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2a650 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2a660 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a670 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
2a680 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
2a690 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
2a6a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
2a6b0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2a6c0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
2a6d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a6e0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
2a6f0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
2a700 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2a710 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
2a720 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
2a730 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
2a740 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2a750 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
2a760 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
2a770 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
2a780 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
2a790 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
2a7a0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
2a7b0 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
2a7c0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
2a7d0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2a7e0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
2a7f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a800 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
2a810 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
2a820 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
2a830 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2a840 6f 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20  on16(). ^In all 
2a850 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  cases.** the nam
2a860 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74  e is passed as t
2a870 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2a880 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
2a890 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2a8a0 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
2a8b0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
2a8c0 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
2a8d0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
2a8e0 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16LE], or [SQLIT
2a8f0 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
2a900 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
2a910 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
2a920 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
2a930 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
2a940 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
2a950 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
2a960 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
2a970 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20   little-endian, 
2a980 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
2a990 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
2a9a0 6c 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72  ly. ^The.** thir
2a9b0 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
2a9c0 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
2a9d0 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63  _UTF16] to indic
2a9e0 61 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75  ate that the rou
2a9f0 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20  tine.** expects 
2aa00 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55  pointers to be U
2aa10 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e  TF-16 strings in
2aa20 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2aa30 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a   order, or the.*
2aa40 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62  * argument can b
2aa50 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
2aa60 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a  ALIGNED] if the.
2aa70 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
2aa80 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
2aa90 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
2aaa0 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
2aab0 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74  * of UTF-16 in t
2aac0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
2aad0 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  rder..**.** A po
2aae0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
2aaf0 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
2ab00 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
2ab10 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
2ab20 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  * argument.  ^If
2ab30 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
2ab40 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
2ab50 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
2ab60 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2ab70 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
2ab80 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
2ab90 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20  it anymore)..** 
2aba0 5e 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61  ^Each time the a
2abb0 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
2abc0 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
2abd0 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
2abe0 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
2abf0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2ac00 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
2ac10 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
2ac20 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
2ac30 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
2ac40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2ac50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2ac60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2ac70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72  ()..**.** ^The r
2ac80 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e  emaining argumen
2ac90 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ts to the applic
2aca0 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72  ation-supplied r
2acb0 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
2acc0 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
2acd0 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2ace0 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20   (length, data) 
2acf0 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
2ad00 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
2ad10 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
2ad20 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
2ad30 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
2ad40 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
2ad50 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
2ad60 69 73 74 65 72 65 64 2e 20 20 54 68 65 20 61 70  istered.  The ap
2ad70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2ad80 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
2ad90 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
2ada0 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
2adb0 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
2adc0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
2add0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
2ade0 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f  ,.** equal to, o
2adf0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
2ae00 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67  he second string
2ae10 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20  . i.e. (STRING1 
2ae20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a  - STRING2)..**.*
2ae30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2ae40 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2ae50 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
2ae60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ae70 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78  ollation().** ex
2ae80 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b  cept that it tak
2ae90 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75  es an extra argu
2aea0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2aeb0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a  destructor for.*
2aec0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e  * the collation.
2aed0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
2aee0 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
2aef0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
2af00 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
2af10 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
2af20 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
2af30 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
2af40 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
2af50 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
2af60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2af70 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
2af80 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
2af90 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
2afa0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
2afb0 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  r calls to the.*
2afc0 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  * collation crea
2afd0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
2afe0 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61  r when the [data
2aff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b000 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73   is closed.** us
2b010 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
2b020 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  se()]..**.** See
2b030 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
2b040 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b050 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
2b060 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2b070 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
2b080 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b090 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
2b0a0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2b0b0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2b0c0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2b0d0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2b0e0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2b0f0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2b100 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2b110 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2b120 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2b130 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
2b140 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2b150 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2b160 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2b170 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2b180 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2b190 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2b1a0 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
2b1b0 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
2b1c0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2b1d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b1e0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
2b1f0 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
2b200 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
2b210 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2b220 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2b230 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2b240 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2b250 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
2b260 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2b270 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
2b280 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
2b290 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
2b2a0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
2b2b0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2b2c0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
2b2d0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
2b2e0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
2b2f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2b300 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
2b310 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
2b320 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b330 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  on] to be invoke
2b340 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e  d whenever an un
2b350 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2b360 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73  n.** sequence is
2b370 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
2b380 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
2b390 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
2b3a0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2b3b0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2b3c0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
2b3d0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
2b3e0 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
2b3f0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
2b400 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
2b410 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
2b420 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71  in UTF-8. ^If sq
2b430 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2b440 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
2b450 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
2b460 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
2b470 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
2b480 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2b490 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  er..** ^A call t
2b4a0 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
2b4b0 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65  n replaces the e
2b4c0 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f  xisting collatio
2b4d0 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63  n-needed callbac
2b4e0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20  k..**.** ^(When 
2b4f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
2b500 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72  invoked, the fir
2b510 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  st argument pass
2b520 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20  ed is a copy.** 
2b530 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  of the second ar
2b540 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2b550 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2b560 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  ed() or.** sqlit
2b570 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2b580 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65  ded16().  The se
2b590 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2b5a0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
2b5b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
2b5c0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2b5d0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2b5e0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2b5f0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f  E_UTF16BE],.** o
2b600 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2b610 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74  E], indicating t
2b620 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c  he most desirabl
2b630 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f  e form of the co
2b640 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
2b650 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  nce function req
2b660 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72  uired.  The four
2b670 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2b680 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a  the name of the.
2b690 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c  ** required coll
2b6a0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29  ation sequence.)
2b6b0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ^.**.** The call
2b6c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
2b6d0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
2b6e0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
2b6f0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
2b700 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b710 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
2b720 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b730 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
2b740 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2b750 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
2b760 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2b770 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b780 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  d(.  sqlite3*, .
2b790 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64    void*, .  void
2b7a0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2b7b0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c  3*,int eTextRep,
2b7c0 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a  const char*).);.
2b7d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
2b7e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
2b7f0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2b800 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
2b810 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
2b820 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
2b830 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
2b840 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
2b850 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
2b860 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
2b870 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
2b880 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
2b890 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
2b8a0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
2b8b0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
2b8c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
2b8d0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2b8e0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2b8f0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2b900 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2b910 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2b920 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
2b930 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2b940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b950 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2b960 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2b970 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2b980 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2b990 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29   /* The key */.)
2b9a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20  ;../*.** Change 
2b9b0 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70  the key on an op
2b9c0 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66  en database.  If
2b9d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
2b9e0 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20  abase is not.** 
2b9f0 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20  encrypted, this 
2ba00 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63  routine will enc
2ba10 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65  rypt it.  If pNe
2ba20 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c  w==0 or nNew==0,
2ba30 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2ba40 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a   is decrypted..*
2ba50 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
2ba60 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
2ba70 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
2ba80 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
2ba90 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
2baa0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
2bab0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
2bac0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2bad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bae0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2baf0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2bb00 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2bb10 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2bb20 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
2bb30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
2bb40 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2bb50 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
2bb60 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
2bb70 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
2bb80 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
2bb90 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2bba0 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
2bbb0 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65  te3_activate_see
2bbc0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2bbd0 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2bbe0 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2bbf0 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2bc00 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c  ndif..#ifdef SQL
2bc10 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44  ITE_ENABLE_CEROD
2bc20 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2bc30 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2bc40 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61  y for a CEROD da
2bc50 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
2bc60 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
2bc70 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44  one of the CEROD
2bc80 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
2bc90 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
2bca0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65  ite3_activate_ce
2bcb0 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  rod(.  const cha
2bcc0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2bcd0 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2bce0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2bcf0 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2bd00 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64  API3REF: Suspend
2bd10 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41   Execution For A
2bd20 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a   Short Time.**.*
2bd30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2bd40 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
2bd50 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
2bd60 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
2bd70 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
2bd80 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
2bd90 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
2bda0 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
2bdb0 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
2bdc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
2bdd0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2bde0 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70  em does not supp
2bdf0 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73  ort sleep reques
2be00 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69  ts with.** milli
2be10 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f  second time reso
2be20 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  lution, then the
2be30 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f   time will be ro
2be40 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74  unded up to.** t
2be50 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e  he nearest secon
2be60 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  d. ^The number o
2be70 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
2be80 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
2be90 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
2bea0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
2beb0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
2bec0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
2bed0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
2bee0 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
2bef0 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
2bf00 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
2bf10 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
2bf20 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
2bf30 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ct..*/.int sqlit
2bf40 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
2bf50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2bf60 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
2bf70 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
2bf80 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
2bf90 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
2bfa0 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
2bfb0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
2bfc0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2bfd0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2bfe0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
2bff0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
2c000 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
2c010 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
2c020 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
2c030 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
2c040 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
2c050 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
2c060 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
2c070 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
2c080 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
2c090 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
2c0a0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
2c0b0 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
2c0c0 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
2c0d0 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
2c0e0 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
2c0f0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
2c100 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
2c110 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
2c120 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
2c130 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
2c140 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
2c150 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2c160 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
2c170 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2c180 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
2c190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
2c1a0 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
2c1b0 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
2c1c0 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
2c1d0 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
2c1e0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
2c1f0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
2c200 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
2c210 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
2c220 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
2c230 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
2c240 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
2c250 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
2c260 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
2c270 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
2c280 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
2c290 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
2c2a0 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
2c2b0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
2c2c0 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
2c2d0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
2c2e0 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
2c2f0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
2c300 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2c310 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2c320 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
2c330 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
2c340 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
2c350 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
2c360 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
2c370 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
2c380 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
2c390 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
2c3a0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
2c3b0 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
2c3c0 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
2c3d0 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
2c3e0 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
2c3f0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
2c400 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
2c410 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
2c420 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
2c430 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
2c440 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
2c450 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
2c460 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
2c470 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2c480 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2c490 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
2c4a0 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
2c4b0 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
2c4c0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
2c4d0 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
2c4e0 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c   avoided..*/.SQL
2c4f0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
2c500 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
2c510 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
2c520 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
2c530 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
2c540 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
2c550 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
2c560 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
2c570 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
2c580 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
2c590 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
2c5a0 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
2c5b0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
2c5c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c5d0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
2c5e0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
2c5f0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
2c600 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
2c610 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
2c620 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
2c630 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
2c640 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
2c650 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2c660 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2c670 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
2c680 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
2c690 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
2c6a0 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
2c6b0 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
2c6c0 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
2c6d0 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
2c6e0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
2c6f0 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
2c700 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
2c710 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
2c720 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
2c730 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
2c740 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
2c750 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
2c760 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
2c770 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
2c780 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
2c790 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2c7a0 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
2c7b0 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
2c7c0 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
2c7d0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2c7e0 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
2c7f0 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
2c800 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
2c810 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
2c820 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
2c830 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
2c840 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
2c850 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
2c860 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2c870 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
2c880 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
2c890 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
2c8a0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
2c8b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e  undefined..*/.in
2c8c0 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  t sqlite3_get_au
2c8d0 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33  tocommit(sqlite3
2c8e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2c8f0 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61  REF: Find The Da
2c900 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66  tabase Handle Of
2c910 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2c920 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ement.**.** ^The
2c930 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
2c940 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
2c950 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
2c960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
2c970 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
2c980 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
2c990 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
2c9a0 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73  .  ^The [databas
2c9b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2c9c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2c9d0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
2c9e0 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  s the same [data
2c9f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ca00 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65  .** that was the
2ca10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2ca20 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2ca30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ca40 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
2ca50 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
2ca60 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
2ca70 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2ca80 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
2ca90 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20  ace..*/.sqlite3 
2caa0 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
2cab0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2cac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cad0 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78  EF: Find the nex
2cae0 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2caf0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ment.**.** ^This
2cb00 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cb10 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2cb20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72  the next [prepar
2cb30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66  ed statement] af
2cb40 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73  ter.** pStmt ass
2cb50 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2cb60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2cb70 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66  ction] pDb.  ^If
2cb80 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a   pStmt is NULL.*
2cb90 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65  * then this inte
2cba0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2cbb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2cbc0 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74  irst prepared st
2cbd0 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63  atement.** assoc
2cbe0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64  iated with the d
2cbf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cc00 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20  on pDb.  ^If no 
2cc10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cc20 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
2cc30 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
2cc40 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
2cc50 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
2cc60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
2cc70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cc80 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
2cc90 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2cca0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
2ccb0 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
2ccc0 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
2ccd0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2cce0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
2ccf0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
2cd00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2cd10 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
2cd20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
2cd30 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
2cd40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2cd50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2cd60 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
2cd70 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
2cd80 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2cd90 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2cda0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2cdb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2cdc0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2cdd0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
2cde0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2cdf0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
2ce00 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20  on is [COMMIT | 
2ce10 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e  committed]..** ^
2ce20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2ce30 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2ce40 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
2ce50 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  ommit_hook().** 
2ce60 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2ce70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ce80 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2ce90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cea0 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20  rollback_hook() 
2ceb0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2cec0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2ced0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2cee0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2cef0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2cf00 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  is [ROLLBACK | r
2cf10 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20  olled back]..** 
2cf20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
2cf30 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
2cf40 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
2cf50 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a  rollback_hook().
2cf60 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2cf70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cf80 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2cf90 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20  n..** ^The pArg 
2cfa0 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73  argument is pass
2cfb0 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
2cfc0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e  e callback..** ^
2cfd0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
2cfe0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
2cff0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
2d000 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
2d010 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
2d020 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
2d030 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
2d040 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d050 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c  commit_hook(D,C,
2d060 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  P) and sqlite3_r
2d070 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43  ollback_hook(D,C
2d080 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ,P) functions.**
2d090 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72   return the P ar
2d0a0 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
2d0b0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66  previous call of
2d0c0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2d0d0 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  on.** on the sam
2d0e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2d0f0 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
2d100 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
2d110 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63  rst call for eac
2d120 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e  h function on D.
2d130 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2d140 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ack implementati
2d150 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
2d160 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
2d170 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
2d180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d190 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
2d1a0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
2d1b0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2d1c0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2d1d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d1e0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2d1f0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2d200 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2d210 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2d220 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2d230 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2d240 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c  commit.** or rol
2d250 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68  lback hook in th
2d260 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
2d270 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
2d280 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d290 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2d2a0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
2d2b0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
2d2c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d2d0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
2d2e0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
2d2f0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
2d300 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72  .**.** ^Register
2d310 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74  ing a NULL funct
2d320 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65  ion disables the
2d330 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
2d340 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69   ^When the commi
2d350 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20  t hook callback 
2d360 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2d370 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49  zero, the [COMMI
2d380 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  T].** operation 
2d390 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f  is allowed to co
2d3a0 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e  ntinue normally.
2d3b0 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74    ^If the commit
2d3c0 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73   hook.** returns
2d3d0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
2d3e0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20  the [COMMIT] is 
2d3f0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
2d400 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20   [ROLLBACK]..** 
2d410 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f  ^The rollback ho
2d420 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ok is invoked on
2d430 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74   a rollback that
2d440 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20   results from a 
2d450 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72  commit.** hook r
2d460 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72  eturning non-zer
2d470 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f  o, just as it wo
2d480 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20  uld be with any 
2d490 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a  other rollback..
2d4a0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
2d4b0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
2d4c0 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
2d4d0 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
2d4e0 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
2d4f0 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
2d500 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
2d510 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
2d520 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
2d530 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
2d540 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
2d550 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
2d560 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54   to occur..** ^T
2d570 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c  he rollback call
2d580 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
2d590 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63  ked if a transac
2d5a0 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  tion is.** autom
2d5b0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2d5c0 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65  back because the
2d5d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d5e0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
2d5f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
2d600 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  he [sqlite3_upda
2d610 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72  te_hook()] inter
2d620 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  face..*/.void *s
2d630 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2d640 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
2d650 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
2d660 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  *);.void *sqlite
2d670 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2d680 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
2d690 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a  )(void *), void*
2d6a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d6b0 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20  EF: Data Change 
2d6c0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
2d6d0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
2d6e0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
2d6f0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
2d700 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
2d710 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
2d720 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ** with the [dat
2d730 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d740 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  ] identified by 
2d750 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2d760 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  nt.** to be invo
2d770 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72  ked whenever a r
2d780 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
2d790 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
2d7a0 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  ed..** ^Any call
2d7b0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
2d7c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
2d7d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
2d7e0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2d7f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d800 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2d810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2d820 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
2d830 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66  pointer to the f
2d840 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b  unction to invok
2d850 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20  e when a.** row 
2d860 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2d870 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2d880 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2d890 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
2d8a0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
2d8b0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
2d8c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
2d8d0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2d8e0 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63  k()..** ^The sec
2d8f0 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67  ond callback arg
2d900 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
2d910 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c  [SQLITE_INSERT],
2d920 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
2d930 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
2d940 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69  UPDATE], dependi
2d950 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
2d960 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
2d970 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
2d980 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a  to be invoked..*
2d990 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
2d9a0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2d9b0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
2d9c0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
2d9d0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
2d9e0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
2d9f0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
2da00 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
2da10 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20  ..** ^The final 
2da20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
2da30 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  er is the [rowid
2da40 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a  ] of the row..**
2da50 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66   ^In the case of
2da60 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73   an update, this
2da70 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
2da80 61 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65  after the update
2da90 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a   takes place..**
2daa0 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65  .** ^(The update
2dab0 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76   hook is not inv
2dac0 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e  oked when intern
2dad0 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73  al system tables
2dae0 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   are.** modified
2daf0 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61   (i.e. sqlite_ma
2db00 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
2db10 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a  sequence).)^.**.
2db20 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65  ** ^In the curre
2db30 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2db40 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  n, the update ho
2db50 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76  ok.** is not inv
2db60 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63  oked when duplic
2db70 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64  ation rows are d
2db80 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f  eleted because o
2db90 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46  f an.** [ON CONF
2dba0 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49  LICT | ON CONFLI
2dbb0 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75  CT REPLACE] clau
2dbc0 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65  se.  ^Nor is the
2dbd0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2dbe0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
2dbf0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
2dc00 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
2dc10 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
2dc20 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
2dc30 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
2dc40 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
2dc50 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
2dc60 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
2dc70 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2dc80 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
2dc90 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2dca0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2dcb0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2dcc0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2dcd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dce0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2dcf0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
2dd00 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
2dd10 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
2dd20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dd30 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
2dd40 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
2dd50 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
2dd60 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2dd70 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
2dd80 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
2dd90 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
2dda0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2ddb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2ddc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2ddd0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2dde0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2ddf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2de00 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2de10 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2de20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2de30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2de40 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44  e3_update_hook(D
2de50 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  ,C,P) function.*
2de60 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20  * returns the P 
2de70 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
2de80 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a  e previous call.
2de90 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2dea0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2deb0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2dec0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2ded0 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a   call on D..**.*
2dee0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2def0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2df00 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ook()] and [sqli
2df10 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2df20 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  k()].** interfac
2df30 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  es..*/.void *sql
2df40 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2df50 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2df60 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c   void(*)(void *,
2df70 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20  int ,char const 
2df80 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73  *,char const *,s
2df90 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20  qlite3_int64),. 
2dfa0 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a   void*.);../*.**
2dfb0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
2dfc0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61  e Or Disable Sha
2dfd0 72 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a  red Pager Cache.
2dfe0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
2dff0 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a  ared cache}.**.*
2e000 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2e010 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
2e020 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
2e030 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2e040 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
2e050 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
2e060 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
2e070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e080 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
2e090 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
2e0a0 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
2e0b0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
2e0c0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
2e0d0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
2e0e0 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
2e0f0 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e  ment is false.)^
2e100 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68  .**.** ^Cache sh
2e110 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
2e120 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f   and disabled fo
2e130 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63  r an entire proc
2e140 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ess..** This is 
2e150 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
2e160 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
2e170 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
2e180 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2e190 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
2e1a0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2e1b0 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
2e1c0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
2e1d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63  .**.** ^(The cac
2e1e0 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20  he sharing mode 
2e1f0 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65  set by this inte
2e200 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c  rface effects al
2e210 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
2e220 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2e230 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
2e240 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2e250 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  and [sqlite3_ope
2e260 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74  n16()]..** Exist
2e270 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ing database con
2e280 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  nections continu
2e290 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e  e use the sharin
2e2a0 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77  g mode.** that w
2e2b0 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20  as in effect at 
2e2c0 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65  the time they we
2e2d0 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a  re opened.)^.**.
2e2e0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2e2f0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
2e300 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20  E_OK] if shared 
2e310 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65  cache was enable
2e320 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
2e330 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2e340 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  An [error code] 
2e350 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65  is returned othe
2e360 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rwise.)^.**.** ^
2e370 53 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20  Shared cache is 
2e380 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
2e390 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69  ult. But this mi
2e3a0 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ght change in.**
2e3b0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2e3c0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70   of SQLite.  App
2e3d0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63  lications that c
2e3e0 61 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64  are about shared
2e3f0 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e  .** cache settin
2e400 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20  g should set it 
2e410 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a  explicitly..**.*
2e420 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51  * See Also:  [SQ
2e430 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68  Lite Shared-Cach
2e440 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73  e Mode].*/.int s
2e450 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
2e460 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b  ared_cache(int);
2e470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e480 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65  : Attempt To Fre
2e490 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a  e Heap Memory.**
2e4a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e4b0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2e4c0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2e4d0 6d 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62  mpts to free N b
2e4e0 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20  ytes.** of heap 
2e4f0 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f  memory by deallo
2e500 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e  cating non-essen
2e510 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  tial memory allo
2e520 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20  cations.** held 
2e530 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
2e540 6c 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72  library.   Memor
2e550 79 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20  y used to cache 
2e560 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65  database.** page
2e570 73 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72  s to improve per
2e580 66 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65  formance is an e
2e590 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73  xample of non-es
2e5a0 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a  sential memory..
2e5b0 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65  ** ^sqlite3_rele
2e5c0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74  ase_memory() ret
2e5d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2e5e0 6f 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c  of bytes actuall
2e5f0 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63  y freed,.** whic
2e600 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20  h might be more 
2e610 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  or less than the
2e620 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65   amount requeste
2e630 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2e640 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2e650 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2e660 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41  PI3REF: Impose A
2e670 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
2e680 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ize.**.** ^The s
2e690 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
2e6a0 5f 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61  _limit() interfa
2e6b0 63 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66  ce places a "sof
2e6c0 74 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74  t" limit.** on t
2e6d0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
2e6e0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
2e6f0 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
2e700 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66  y SQLite..** ^If
2e710 20 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c   an internal all
2e720 6f 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  ocation is reque
2e730 73 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20  sted that would 
2e740 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f  exceed the.** so
2e750 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b  ft heap limit, [
2e760 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2e770 6d 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76  memory()] is inv
2e780 6f 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d  oked one or.** m
2e790 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65  ore times to fre
2e7a0 65 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20  e up some space 
2e7b0 62 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63  before the alloc
2e7c0 61 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  ation is perform
2e7d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c  ed..**.** ^The l
2e7e0 69 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22  imit is called "
2e7f0 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66  soft" because if
2e800 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2e810 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63  e_memory()].** c
2e820 61 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69  annot free suffi
2e830 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20  cient memory to 
2e840 70 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69  prevent the limi
2e850 74 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63  t from being exc
2e860 65 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65  eeded,.** the me
2e870 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65  mory is allocate
2e880 64 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65  d anyway and the
2e890 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69   current operati
2e8a0 6f 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a  on proceeds..**.
2e8b0 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f  ** ^A negative o
2e8c0 72 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72  r zero value for
2e8d0 20 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68   N means that th
2e8e0 65 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68  ere is no soft h
2e8f0 65 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a  eap limit and.**
2e900 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
2e910 65 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c  e_memory()] will
2e920 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2e930 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65  when memory is e
2e940 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68  xhausted..** ^Th
2e950 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
2e960 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2e970 70 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e  p limit is zero.
2e980 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
2e990 6d 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66  makes a best eff
2e9a0 6f 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65  ort to honor the
2e9b0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2e9c0 2e 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20  ..** But if the 
2e9d0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2e9e0 63 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65  cannot be honore
2e9f0 64 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c  d, execution wil
2ea00 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69  l.** continue wi
2ea10 74 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e  thout error or n
2ea20 6f 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20  otification.)^  
2ea30 54 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20  This is why the 
2ea40 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c  limit is.** call
2ea50 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  ed a "soft" limi
2ea60 74 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f  t.  It is adviso
2ea70 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50  ry only..**.** P
2ea80 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
2ea90 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2eaa0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
2eab0 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20  constrained the 
2eac0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
2ead0 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ted by a single 
2eae0 74 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d  thread - the sam
2eaf0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2eb00 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  h this routine.*
2eb10 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69  * runs.  Beginni
2eb20 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
2eb30 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68  ersion 3.5.0, th
2eb40 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
2eb50 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20  t is.** applied 
2eb60 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  to all threads. 
2eb70 54 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66  The value specif
2eb80 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74  ied for the soft
2eb90 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69   heap limit.** i
2eba0 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64  s an upper bound
2ebb0 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65   on the total me
2ebc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2ebd0 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  for all threads.
2ebe0 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33   In.** version 3
2ebf0 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f  .5.0 there is no
2ec00 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c   mechanism for l
2ec10 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70  imiting the heap
2ec20 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e   usage for.** in
2ec30 64 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73  dividual threads
2ec40 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2ec50 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2ec60 74 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t(int);../*.** C
2ec70 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
2ec80 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
2ec90 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
2eca0 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
2ecb0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ecc0 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
2ecd0 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
2ece0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
2ecf0 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
2ed00 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
2ed10 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
2ed20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2ed30 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
2ed40 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
2ed50 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
2ed60 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
2ed70 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
2ed80 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
2ed90 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
2eda0 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
2edb0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
2edc0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2edd0 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
2ede0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2edf0 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
2ee00 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
2ee10 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
2ee20 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
2ee30 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
2ee40 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
2ee50 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
2ee60 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
2ee70 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
2ee80 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
2ee90 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
2eea0 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
2eeb0 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
2eec0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2eed0 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
2eee0 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
2eef0 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
2ef00 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2ef10 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2ef20 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2ef30 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
2ef40 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
2ef50 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
2ef60 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
2ef70 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
2ef80 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
2ef90 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
2efa0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
2efb0 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
2efc0 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
2efd0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
2efe0 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
2eff0 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
2f000 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
2f010 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
2f020 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
2f030 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
2f040 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
2f050 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
2f060 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2f070 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
2f080 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
2f090 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75  **.** ^(<blockqu
2f0a0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2f0b0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2f0c0 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
2f0d0 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
2f0e0 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
2f0f0 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
2f100 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
2f110 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2f120 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
2f130 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
2f140 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2f150 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
2f160 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2f170 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
2f180 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2f190 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2f1a0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
2f1b0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2f1c0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
2f1d0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2f1e0 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2f1f0 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
2f200 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
2f210 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
2f220 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2f230 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2f240 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
2f250 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
2f260 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2f270 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
2f280 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
2f290 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
2f2a0 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
2f2b0 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
2f2c0 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
2f2d0 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
2f2e0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
2f2f0 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
2f300 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
2f310 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
2f320 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
2f330 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
2f340 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
2f350 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61  tually a view, a
2f360 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2f370 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2f380 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2f390 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
2f3a0 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
2f3b0 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
2f3c0 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
2f3d0 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2f3e0 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
2f3f0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
2f400 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2f410 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2f420 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
2f430 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2f440 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68   column. ^(If th
2f450 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
2f460 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2f470 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2f480 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
2f490 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2f4a0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2f4b0 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
2f4c0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
2f4d0 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
2f4e0 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
2f4f0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2f500 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
2f510 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
2f520 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
2f530 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
2f540 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
2f550 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
2f560 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
2f570 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
2f580 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
2f590 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
2f5a0 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
2f5b0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2f5c0 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
2f5d0 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
2f5e0 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
2f5f0 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
2f600 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
2f610 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2f620 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
2f630 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
2f640 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2f650 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
2f660 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
2f670 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
2f680 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  g()).)^.**.** ^T
2f690 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
2f6a0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2f6b0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2f6c0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2f6d0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2f6e0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2f6f0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2f700 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
2f710 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f720 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
2f730 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
2f740 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f750 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
2f760 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
2f770 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
2f780 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
2f790 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
2f7a0 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
2f7b0 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
2f7c0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
2f7d0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
2f7e0 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
2f7f0 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
2f800 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
2f810 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
2f820 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
2f830 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
2f840 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2f850 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
2f860 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
2f870 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2f880 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
2f890 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
2f8a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
2f8b0 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
2f8c0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
2f8d0 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
2f8e0 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
2f8f0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2f900 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
2f910 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
2f920 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
2f930 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
2f940 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
2f950 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
2f960 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
2f970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
2f980 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
2f990 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
2f9a0 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20  erface loads an 
2f9b0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2f9c0 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68   library from th
2f9d0 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a  e named file..**
2f9e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f9f0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2fa00 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2fa10 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a  mpts to load an.
2fa20 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  ** SQLite extens
2fa30 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  ion library cont
2fa40 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c  ained in the fil
2fa50 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  e zFile..**.** ^
2fa60 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  The entry point 
2fa70 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50  is zProc..** ^zP
2fa80 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e  roc may be 0, in
2fa90 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
2faa0 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
2fab0 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75  y point.** defau
2fac0 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
2fad0 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
2fae0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2faf0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2fb00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2fb10 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  rns.** [SQLITE_O
2fb20 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
2fb30 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2fb40 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
2fb50 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66  es wrong..** ^If
2fb60 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2fb70 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
2fb80 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
2fb90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  .** [sqlite3_loa
2fba0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
2fbb0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
2fbc0 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c  ttempt to.** fil
2fbd0 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
2fbe0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2fbf0 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
2fc00 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  mory.** obtained
2fc10 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2fc20 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61  alloc()]. The ca
2fc30 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a  lling function.*
2fc40 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68  * should free th
2fc50 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
2fc60 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
2fc70 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78  ee()]..**.** ^Ex
2fc80 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2fc90 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20  must be enabled 
2fca0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2fcb0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2fcc0 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
2fcd0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
2fce0 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69   API,.** otherwi
2fcf0 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  se an error will
2fd00 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   be returned..**
2fd10 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
2fd20 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
2fd30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
2fd40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2fd50 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2fd60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2fd70 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
2fd80 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
2fd90 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
2fda0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
2fdb0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2fdc0 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
2fdd0 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
2fde0 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
2fdf0 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
2fe00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
2fe10 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
2fe20 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
2fe30 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
2fe40 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
2fe50 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
2fe60 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
2fe70 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
2fe80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fe90 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
2fea0 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
2feb0 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53  Loading.**.** ^S
2fec0 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
2fed0 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
2fee0 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
2fef0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
2ff00 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
2ff10 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
2ff20 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
2ff30 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
2ff40 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
2ff50 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
2ff60 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
2ff70 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
2ff80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
2ff90 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  PI.** is provide
2ffa0 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
2ffb0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2ffc0 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
2ffd0 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a  sm on and off..*
2ffe0 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20  *.** ^Extension 
2fff0 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62  loading is off b
30000 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74  y default. See t
30010 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20  icket #1863..** 
30020 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65  ^Call the sqlite
30030 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
30040 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e  tension() routin
30050 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a  e with onoff==1.
30060 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e  ** to turn exten
30070 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20  sion loading on 
30080 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
30090 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
300a0 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66  n.** it back off
300b0 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73   again..*/.int s
300c0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
300d0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
300e0 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
300f0 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
30100 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63  I3REF: Automatic
30110 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
30120 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  ensions.**.** ^T
30130 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69  his API can be i
30140 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61  nvoked at progra
30150 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64  m startup in ord
30160 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  er to register.*
30170 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74  * one or more st
30180 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20  atically linked 
30190 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20  extensions that 
301a0 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c  will be availabl
301b0 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20  e.** to all new 
301c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
301d0 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tions]..**.** ^(
301e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
301f0 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
30200 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65   the extension e
30210 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e  ntry point.** in
30220 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69   an array that i
30230 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
30240 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
30250 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79  )].  That memory
30260 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74  .** is deallocat
30270 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72  ed by [sqlite3_r
30280 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
30290 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ion()].)^.**.** 
302a0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
302b0 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65  egisters an exte
302c0 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
302d0 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74  t that is.** aut
302e0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b  omatically invok
302f0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ed whenever a ne
30300 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
30310 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70  ection].** is op
30320 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ened using [sqli
30330 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
30340 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
30350 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
30360 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e  open_v2()]..** ^
30370 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
30380 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
30390 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
303a0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c  s routine.** mul
303b0 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
303c0 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
303d0 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
303e0 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65  .** ^Automatic e
303f0 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
30400 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
30410 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
30420 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
30430 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
30440 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
30450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
30460 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
30470 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
30480 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
30490 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
304a0 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
304b0 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61  egistered automa
304c0 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  tic.** extension
304d0 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65  s. It undoes the
304e0 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70   effect of all p
304f0 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rior.** [sqlite3
30500 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
30510 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a  )] calls.)^.**.*
30520 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
30530 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61   disables automa
30540 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
30550 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  n all threads..*
30560 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
30570 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
30580 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
30590 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
305a0 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
305b0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
305c0 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
305d0 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
305e0 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
305f0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
30600 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
30610 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
30620 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
30630 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
30640 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
30650 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
30660 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
30670 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
30680 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
30690 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
306a0 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
306b0 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
306c0 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
306d0 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
306e0 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
306f0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
30700 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
30710 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
30720 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
30730 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
30740 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
30750 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
30760 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
30770 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
30780 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
30790 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
307a0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
307b0 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
307c0 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
307d0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
307e0 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
307f0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
30800 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
30810 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Table Object.** 
30820 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
30830 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61  3_module {virtua
30840 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a  l table module}.
30850 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63  **.** This struc
30860 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20  ture, sometimes 
30870 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74  called a a "virt
30880 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
30890 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74  ", .** defines t
308a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
308b0 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  n of a [virtual 
308c0 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68  tables].  .** Th
308d0 69 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e  is structure con
308e0 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20  sists mostly of 
308f0 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  methods for the 
30900 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41  module..**.** ^A
30910 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
30920 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64  odule is created
30930 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61   by filling in a
30940 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69   persistent.** i
30950 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
30960 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61  structure and pa
30970 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20  ssing a pointer 
30980 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65  to that instance
30990 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
309a0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
309b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
309c0 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d  ate_module_v2()]
309d0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74  ..** ^The regist
309e0 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76  ration remains v
309f0 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73  alid until it is
30a00 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64   replaced by a d
30a10 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75  ifferent.** modu
30a20 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  le or until the 
30a30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30a40 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54  tion] closes.  T
30a50 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66  he content.** of
30a60 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
30a70 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20  must not change 
30a80 77 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69  while it is regi
30a90 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61  stered with.** a
30aa0 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
30ab0 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63  ection..*/.struc
30ac0 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
30ad0 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
30ae0 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61  n;.  int (*xCrea
30af0 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  te)(sqlite3*, vo
30b00 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
30b10 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
30b20 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
30b30 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
30b40 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
30b50 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
30b60 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
30b70 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69  (*xConnect)(sqli
30b80 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
30b90 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30ba0 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
30bb0 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
30bc0 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
30bd0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
30be0 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
30bf0 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49  ;.  int (*xBestI
30c00 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74  ndex)(sqlite3_vt
30c10 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
30c20 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b  e3_index_info*);
30c30 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e  .  int (*xDiscon
30c40 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74  nect)(sqlite3_vt
30c50 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
30c60 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71  t (*xDestroy)(sq
30c70 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30c80 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65  b);.  int (*xOpe
30c90 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
30ca0 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
30cb0 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70  vtab_cursor **pp
30cc0 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28  Cursor);.  int (
30cd0 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
30ce0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
30cf0 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29    int (*xFilter)
30d00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
30d10 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75  rsor*, int idxNu
30d20 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69  m, const char *i
30d30 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20  dxStr,.         
30d40 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
30d50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
30d60 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a  *argv);.  int (*
30d70 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76  xNext)(sqlite3_v
30d80 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
30d90 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69  int (*xEof)(sqli
30da0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
30db0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75  );.  int (*xColu
30dc0 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  mn)(sqlite3_vtab
30dd0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
30de0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
30df0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64  ;.  int (*xRowid
30e00 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
30e10 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
30e20 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a  int64 *pRowid);.
30e30 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29    int (*xUpdate)
30e40 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c  (sqlite3_vtab *,
30e50 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61   int, sqlite3_va
30e60 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f  lue **, sqlite3_
30e70 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20  int64 *);.  int 
30e80 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65  (*xBegin)(sqlite
30e90 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
30ea0 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
30eb0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
30ec0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  ab);.  int (*xCo
30ed0 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74  mmit)(sqlite3_vt
30ee0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
30ef0 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73  t (*xRollback)(s
30f00 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
30f10 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ab);.  int (*xFi
30f20 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69  ndFunction)(sqli
30f30 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
30f40 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74   int nArg, const
30f50 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20   char *zName,.  
30f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30f70 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46       void (**pxF
30f80 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
30f90 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
30fa0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20  3_value**),.    
30fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30fc0 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29     void **ppArg)
30fd0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d  ;.  int (*xRenam
30fe0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
30ff0 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68  *pVtab, const ch
31000 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f  ar *zNew);.};../
31010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
31020 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64  irtual Table Ind
31030 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f  exing Informatio
31040 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  n.** KEYWORDS: s
31050 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
31060 6f 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  o.**.** The sqli
31070 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
31080 74 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73  tructure and its
31090 20 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69   substructures i
310a0 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73  s used to.** pas
310b0 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e  s information in
310c0 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74  to and receive t
310d0 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68  he reply from th
310e0 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a  e [xBestIndex].*
310f0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76  * method of a [v
31100 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
31110 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64  ule].  The field
31120 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73  s under **Inputs
31130 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  ** are the.** in
31140 70 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64  puts to xBestInd
31150 65 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d  ex and are read-
31160 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65  only.  xBestInde
31170 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a  x inserts its.**
31180 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68   results into th
31190 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69  e **Outputs** fi
311a0 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  elds..**.** ^(Th
311b0 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
311c0 61 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48  array records WH
311d0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
311e0 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  raints of the fo
311f0 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63  rm:.**.** <pre>c
31200 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70  olumn OP expr</p
31210 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  re>.**.** where 
31220 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26  OP is =, &lt;, &
31230 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26  lt;=, &gt;, or &
31240 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70  gt;=.)^  ^(The p
31250 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74  articular operat
31260 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20  or is.** stored 
31270 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  in aConstraint[]
31280 2e 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e  .op.)^  ^(The in
31290 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
312a0 6e 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a  n is stored in.*
312b0 2a 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  * aConstraint[].
312c0 69 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43  iColumn.)^  ^(aC
312d0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62  onstraint[].usab
312e0 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68  le is TRUE if th
312f0 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65  e.** expr on the
31300 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
31310 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65   can be evaluate
31320 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20  d (and thus the 
31330 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73  constraint.** is
31340 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c   usable) and fal
31350 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e  se if it cannot.
31360 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70  )^.**.** ^The op
31370 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69  timizer automati
31380 63 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65  cally inverts te
31390 72 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  rms of the form 
313a0 22 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22  "expr OP column"
313b0 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74  .** and makes ot
313c0 68 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69  her simplificati
313d0 6f 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45  ons to the WHERE
313e0 20 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74   clause in an at
313f0 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20  tempt to.** get 
31400 61 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c  as many WHERE cl
31410 61 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20  ause terms into 
31420 74 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61  the form shown a
31430 62 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65  bove as possible
31440 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74  ..** ^The aConst
31450 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e  raint[] array on
31460 6c 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45  ly reports WHERE
31470 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68   clause terms th
31480 61 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61  at are.** releva
31490 6e 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63  nt to the partic
314a0 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62  ular virtual tab
314b0 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64  le being queried
314c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61  ..**.** ^Informa
314d0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
314e0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
314f0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
31500 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68  erBy[]..** ^Each
31510 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42   term of aOrderB
31520 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75  y records a colu
31530 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20  mn of the ORDER 
31540 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a  BY clause..**.**
31550 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   The [xBestIndex
31560 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  ] method must fi
31570 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
31580 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
31590 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
315a0 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
315b0 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
315c0 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64  er.  ^If argvInd
315d0 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
315e0 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
315f0 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
31600 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
31610 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
31620 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
31630 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
31640 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
31650 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e   ^(If aConstrain
31660 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a  tUsage[].omit.**
31670 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
31680 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  he constraint is
31690 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66   assumed to be f
316a0 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20  ully handled by 
316b0 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  the.** virtual t
316c0 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20  able and is not 
316d0 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79  checked again by
316e0 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a   SQLite.)^.**.**
316f0 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64   ^The idxNum and
31700 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
31710 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
31720 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a  passed into the.
31730 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74  ** [xFilter] met
31740 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65  hod..** ^[sqlite
31750 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65  3_free()] is use
31760 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
31770 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
31780 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  ** needToFreeIdx
31790 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a  Ptr is true..**.
317a0 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43  ** ^The orderByC
317b0 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68  onsumed means th
317c0 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b  at output from [
317d0 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d  xFilter]/[xNext]
317e0 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a   will occur in.*
317f0 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72  * the correct or
31800 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74  der to satisfy t
31810 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
31820 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65  se so that no se
31830 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e  parate.** sortin
31840 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72  g step is requir
31850 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  ed..**.** ^The e
31860 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c  stimatedCost val
31870 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ue is an estimat
31880 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66  e of the cost of
31890 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61   doing the.** pa
318a0 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e  rticular lookup.
318b0 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66    A full scan of
318c0 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20   a table with N 
318d0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
318e0 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66  ave.** a cost of
318f0 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65   N.  A binary se
31900 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20  arch of a table 
31910 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  of N entries sho
31920 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f  uld have a.** co
31930 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74  st of approximat
31940 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73  ely log(N)..*/.s
31950 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
31960 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20  dex_info {.  /* 
31970 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20  Inputs */.  int 
31980 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  nConstraint;    
31990 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
319a0 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61   of entries in a
319b0 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  Constraint */.  
319c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
319d0 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20  ndex_constraint 
319e0 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
319f0 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
31a00 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65   /* Column on le
31a10 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
31a20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
31a30 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
31a40 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   op;         /* 
31a50 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61  Constraint opera
31a60 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  tor */.     unsi
31a70 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65  gned char usable
31a80 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66  ;     /* True if
31a90 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
31aa0 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20   is usable */.  
31ab0 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73     int iTermOffs
31ac0 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  et;          /* 
31ad0 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  Used internally 
31ae0 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f  - xBestIndex sho
31af0 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20  uld ignore */.  
31b00 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20  } *aConstraint; 
31b10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61             /* Ta
31b20 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61  ble of WHERE cla
31b30 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
31b40 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42  */.  int nOrderB
31b50 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
31b60 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72  /* Number of ter
31b70 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  ms in the ORDER 
31b80 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73  BY clause */.  s
31b90 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
31ba0 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20  dex_orderby {.  
31bb0 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
31bc0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31bd0 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f  Column number */
31be0 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
31bf0 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20  har desc;       
31c00 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43  /* True for DESC
31c10 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43  .  False for ASC
31c20 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72  . */.  } *aOrder
31c30 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
31c40 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42    /* The ORDER B
31c50 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a  Y clause */.  /*
31c60 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74   Outputs */.  st
31c70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
31c80 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73  ex_constraint_us
31c90 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72  age {.    int ar
31ca0 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20  gvIndex;        
31cb0 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e     /* if >0, con
31cc0 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20  straint is part 
31cd0 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74  of argv to xFilt
31ce0 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e  er */.    unsign
31cf0 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20  ed char omit;   
31d00 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64     /* Do not cod
31d10 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69  e a test for thi
31d20 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  s constraint */.
31d30 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
31d40 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78  Usage;.  int idx
31d50 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
31d60 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
31d70 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
31d80 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68  he index */.  ch
31d90 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20  ar *idxStr;     
31da0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69           /* Stri
31db0 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74  ng, possibly obt
31dc0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
31dd0 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69  e3_malloc */.  i
31de0 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  nt needToFreeIdx
31df0 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65  Str;      /* Fre
31e00 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73  e idxStr using s
31e10 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66  qlite3_free() if
31e20 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f   true */.  int o
31e30 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20  rderByConsumed; 
31e40 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66        /* True if
31e50 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61   output is alrea
31e60 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20  dy ordered */.  
31e70 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64  double estimated
31e80 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73  Cost;      /* Es
31e90 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20  timated cost of 
31ea0 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78  using this index
31eb0 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53   */.};.#define S
31ec0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
31ed0 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
31ee0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
31ef0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
31f00 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
31f10 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
31f20 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
31f30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
31f40 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
31f50 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
31f60 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
31f70 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
31f80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31f90 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
31fa0 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
31fb0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
31fc0 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
31fd0 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
31fe0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
31ff0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
32000 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
32010 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
32020 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e  le module] name.
32030 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65  .** ^Module name
32040 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
32050 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
32060 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76  reating a new [v
32070 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73  irtual table] us
32080 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61  ing the module a
32090 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  nd before using 
320a0 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  a.** preexisting
320b0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
320c0 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
320d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75  .**.** ^The modu
320e0 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73  le name is regis
320f0 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61  tered on the [da
32100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32110 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  n] specified.** 
32120 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
32130 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61  ameter.  ^The na
32140 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
32150 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
32160 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61   .** second para
32170 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69  meter.  ^The thi
32180 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
32190 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
321a0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
321b0 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  on of the [virtu
321c0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
321d0 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a  .   ^The fourth.
321e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
321f0 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69  an arbitrary cli
32200 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ent data pointer
32210 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
32220 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20  through.** into 
32230 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  the [xCreate] an
32240 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
32250 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74  hods of the virt
32260 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
32270 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76  .** when a new v
32280 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
32290 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  be being created
322a0 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65   or reinitialize
322b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
322c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
322d0 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ule_v2() interfa
322e0 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70  ce has a fifth p
322f0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
32300 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
32310 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  o a destructor f
32320 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  or the pClientDa
32330 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  ta.  ^SQLite wil
32340 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  l.** invoke the 
32350 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
32360 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f  ion (if it is no
32370 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c  t NULL) when SQL
32380 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72  ite.** no longer
32390 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65   needs the pClie
323a0 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  ntData pointer. 
323b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
323c0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a  eate_module().**
323d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
323e0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69  uivalent to sqli
323f0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
32400 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
32410 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  LL.** destructor
32420 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32430 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a  _create_module(.
32440 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
32450 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32460 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
32470 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
32480 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
32490 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
324a0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
324b0 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
324c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
324d0 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20  e3_module *p,   
324e0 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
324f0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
32500 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61  oid *pClientData
32510 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69            /* Cli
32520 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
32530 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
32540 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
32550 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
32560 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
32570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
32580 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
32590 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
325a0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
325b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
325c0 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
325d0 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
325e0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
325f0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
32600 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
32610 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
32620 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
32630 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta,         /* C
32640 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
32650 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
32660 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  */.  void(*xDest
32670 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20  roy)(void*)     
32680 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75  /* Module destru
32690 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  ctor function */
326a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
326b0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
326c0 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65  le Instance Obje
326d0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
326e0 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a  sqlite3_vtab.**.
326f0 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
32700 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
32710 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
32720 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a  ses a subclass.*
32730 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  * of this object
32740 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
32750 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
32760 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69  ce.** of the [vi
32770 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45  rtual table].  E
32780 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c  ach subclass wil
32790 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64  l.** be tailored
327a0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
327b0 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f   needs of the mo
327c0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
327d0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70  ion..** The purp
327e0 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
327f0 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
32800 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
32810 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63  ds that are.** c
32820 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64  ommon to all mod
32830 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
32840 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74  ons..**.** ^Virt
32850 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f  ual tables metho
32860 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72  ds can set an er
32870 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61  ror message by a
32880 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74  ssigning a.** st
32890 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
328a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
328b0 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73  ntf()] to zErrMs
328c0 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
328d0 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
328e0 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
328f0 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
32900 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
32910 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
32920 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69  ** prior to assi
32930 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69  gning a new stri
32940 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  ng to zErrMsg.  
32950 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72  ^After the error
32960 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
32970 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
32980 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
32990 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
329a0 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
329b0 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
329c0 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
329d0 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
329e0 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
329f0 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75   zeroed..*/.stru
32a00 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
32a10 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
32a20 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
32a30 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
32a40 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
32a50 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
32a60 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
32a70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32a80 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20   NO LONGER USED 
32a90 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d  */.  char *zErrM
32aa0 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  sg;             
32ab0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65       /* Error me
32ac0 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74  ssage from sqlit
32ad0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a  e3_mprintf() */.
32ae0 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
32af0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
32b00 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
32b10 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
32b20 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
32b30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
32b40 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72  irtual Table Cur
32b50 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  sor Object.** KE
32b60 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
32b70 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72  vtab_cursor {vir
32b80 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f  tual table curso
32b90 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  r}.**.** Every [
32ba0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
32bb0 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
32bc0 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
32bd0 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  lass of the.** f
32be0 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
32bf0 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63  re to describe c
32c00 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e  ursors that poin
32c10 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76  t into the.** [v
32c20 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e  irtual table] an
32c30 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
32c40 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
32c50 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
32c60 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
32c70 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
32c80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ** [sqlite3_modu
32c90 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e  le.xOpen | xOpen
32ca0 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
32cb0 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64  module and are d
32cc0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74  estroyed.** by t
32cd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  he [sqlite3_modu
32ce0 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f  le.xClose | xClo
32cf0 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72  se] method.  Cur
32d00 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a  sors are used.**
32d10 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72   by the [xFilter
32d20 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f  ], [xNext], [xEo
32d30 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61  f], [xColumn], a
32d40 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68  nd [xRowid] meth
32d50 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f  ods.** of the mo
32d60 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75  dule.  Each modu
32d70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
32d80 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a  n will define.**
32d90 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
32da0 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75  a cursor structu
32db0 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f  re to suit its o
32dc0 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  wn needs..**.** 
32dd0 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  This superclass 
32de0 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20  exists in order 
32df0 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73  to define fields
32e00 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74   of the cursor t
32e10 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f  hat.** are commo
32e20 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  n to all impleme
32e30 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72  ntations..*/.str
32e40 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
32e50 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69  _cursor {.  sqli
32e60 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b  te3_vtab *pVtab;
32e70 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c        /* Virtual
32e80 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63   table of this c
32e90 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69  ursor */.  /* Vi
32ea0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
32eb0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
32ec0 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
32ed0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
32ee0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
32ef0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20  PI3REF: Declare 
32f00 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20  The Schema Of A 
32f10 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a  Virtual Table.**
32f20 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74  .** ^The [xCreat
32f30 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
32f40 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
32f50 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
32f60 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
32f70 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
32f80 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
32f90 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
32fa0 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
32fb0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
32fc0 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
32fd0 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
32fe0 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73  lement..*/.int s
32ff0 71 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76  qlite3_declare_v
33000 74 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  tab(sqlite3*, co
33010 6e 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b  nst char *zSQL);
33020 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33030 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e  : Overload A Fun
33040 63 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74  ction For A Virt
33050 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  ual Table.**.** 
33060 5e 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  ^(Virtual tables
33070 20 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74   can provide alt
33080 65 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65  ernative impleme
33090 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63  ntations of func
330a0 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74  tions.** using t
330b0 68 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f  he [xFindFunctio
330c0 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
330d0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
330e0 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75  module].  .** Bu
330f0 74 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  t global version
33100 73 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74  s of those funct
33110 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69  ions.** must exi
33120 73 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62  st in order to b
33130 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a  e overloaded.)^.
33140 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49  **.** ^(This API
33150 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c   makes sure a gl
33160 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20  obal version of 
33170 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
33180 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
33190 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20  name and number 
331a0 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78  of parameters ex
331b0 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63  ists.  If no suc
331c0 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74  h function exist
331d0 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73  s.** before this
331e0 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20   API is called, 
331f0 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  a new function i
33200 73 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54  s created.)^  ^T
33210 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
33220 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20  n.** of the new 
33230 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20  function always 
33240 63 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74  causes an except
33250 69 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e  ion to be thrown
33260 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77  .  So.** the new
33270 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
33280 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69   good for anythi
33290 6e 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49  ng by itself.  I
332a0 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f  ts only.** purpo
332b0 73 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c  se is to be a pl
332c0 61 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69  aceholder functi
332d0 6f 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  on that can be o
332e0 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20  verloaded.** by 
332f0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
33300 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
33310 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74  3_overload_funct
33320 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f  ion(sqlite3*, co
33330 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e  nst char *zFuncN
33340 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a  ame, int nArg);.
33350 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
33360 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
33370 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
33380 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76  ism defined abov
33390 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f  e (back up.** to
333a0 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72   a comment remar
333b0 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f  kably similar to
333c0 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75   this one) is cu
333d0 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
333e0 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
333f0 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
33400 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
33410 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
33420 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
33430 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
33440 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
33450 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
33460 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
33470 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
33480 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
33490 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
334a0 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
334b0 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
334c0 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
334d0 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
334e0 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
334f0 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
33500 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .*/../*.** CAPI3
33510 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f  REF: A Handle To
33520 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
33530 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42   KEYWORDS: {BLOB
33540 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68   handle} {BLOB h
33550 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  andles}.**.** An
33560 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
33570 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
33580 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42  nts an open BLOB
33590 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71   on which.** [sq
335a0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
335b0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
335c0 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70  OB I/O] can be p
335d0 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62  erformed..** ^Ob
335e0 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79  jects of this ty
335f0 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62  pe are created b
33600 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
33610 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64  open()].** and d
33620 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
33630 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
33640 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  )]..** ^The [sql
33650 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
33660 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
33670 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74  lob_write()] int
33680 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62  erfaces.** can b
33690 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f  e used to read o
336a0 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75  r write small su
336b0 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  bsections of the
336c0 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b   BLOB..** ^The [
336d0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
336e0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
336f0 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
33700 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20   of the BLOB in 
33710 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  bytes..*/.typede
33720 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
33730 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c  _blob sqlite3_bl
33740 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ob;../*.** CAPI3
33750 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42  REF: Open A BLOB
33760 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c   For Incremental
33770 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69   I/O.**.** ^(Thi
33780 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65  s interfaces ope
33790 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ns a [BLOB handl
337a0 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74  e | handle] to t
337b0 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a  he BLOB located.
337c0 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20  ** in row iRow, 
337d0 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
337e0 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20  table zTable in 
337f0 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a  database zDb;.**
33800 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
33810 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74   the same BLOB t
33820 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c  hat would be sel
33830 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20  ected by:.**.** 
33840 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c  <pre>.**     SEL
33850 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d  ECT zColumn FROM
33860 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52   zDb.zTable WHER
33870 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77  E [rowid] = iRow
33880 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a  ;.** </pre>)^.**
33890 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67  .** ^If the flag
338a0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
338b0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
338c0 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
338d0 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64   for read.** and
338e0 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e   write access. ^
338f0 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74  If it is zero, t
33900 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65  he BLOB is opene
33910 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73  d for read acces
33920 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74  s..** ^It is not
33930 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65   possible to ope
33940 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  n a column that 
33950 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e  is part of an in
33960 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a  dex or primary .
33970 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69  ** key for writi
33980 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e  ng. ^If [foreign
33990 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73   key constraints
339a0 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69  ] are enabled, i
339b0 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73  t is .** not pos
339c0 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20  sible to open a 
339d0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70  column that is p
339e0 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20  art of a [child 
339f0 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67  key] for writing
33a00 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
33a10 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
33a20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20  name is not the 
33a30 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f  filename that co
33a40 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61  ntains.** the da
33a50 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65  tabase but rathe
33a60 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e  r the symbolic n
33a70 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
33a80 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65  ase that.** appe
33a90 61 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53  ars after the AS
33aa0 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68   keyword when th
33ab0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f  e database is co
33ac0 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41  nnected using [A
33ad0 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20  TTACH]..** ^For 
33ae0 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
33af0 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  e file, the data
33b00 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61  base name is "ma
33b10 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d  in"..** ^For TEM
33b20 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61  P tables, the da
33b30 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
33b40 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  temp"..**.** ^(O
33b50 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49  n success, [SQLI
33b60 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
33b70 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b  ed and the new [
33b80 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20  BLOB handle] is 
33b90 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70  written.** to *p
33ba0 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65  pBlob. Otherwise
33bb0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
33bc0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
33bd0 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a   *ppBlob is set.
33be0 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20  ** to be a null 
33bf0 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54  pointer.)^.** ^T
33c00 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74  his function set
33c10 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
33c20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f  connection] erro
33c30 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
33c40 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65  ge.** accessible
33c50 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72   via [sqlite3_er
33c60 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71  rcode()] and [sq
33c70 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
33c80 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66  and related.** f
33c90 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20  unctions. ^Note 
33ca0 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62  that the *ppBlob
33cb0 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77   variable is alw
33cc0 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  ays initialized 
33cd0 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74  in a.** way that
33ce0 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74   makes it safe t
33cf0 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  o invoke [sqlite
33d00 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20  3_blob_close()] 
33d10 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65  on *ppBlob.** re
33d20 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
33d30 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
33d40 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  re of this routi
33d50 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ne..**.** ^(If t
33d60 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c  he row that a BL
33d70 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73  OB handle points
33d80 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20   to is modified 
33d90 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45  by an.** [UPDATE
33da0 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20  ], [DELETE], or 
33db0 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  by [ON CONFLICT]
33dc0 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a   side-effects.**
33dd0 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68   then the BLOB h
33de0 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20  andle is marked 
33df0 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a  as "expired"..**
33e00 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66   This is true if
33e10 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   any column of t
33e20 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65  he row is change
33e30 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e  d, even a column
33e40 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74  .** other than t
33e50 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20  he one the BLOB 
33e60 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f  handle is open o
33e70 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  n.)^.** ^Calls t
33e80 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
33e90 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  read()] and [sql
33ea0 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
33eb0 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69  )] for.** a expi
33ec0 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  red BLOB handle 
33ed0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74  fail with an ret
33ee0 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  urn code of [SQL
33ef0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e  ITE_ABORT]..** ^
33f00 28 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e  (Changes written
33f10 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69   into a BLOB pri
33f20 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65  or to the BLOB e
33f30 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a  xpiring are not.
33f40 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
33f50 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e  y the expiration
33f60 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53   of the BLOB.  S
33f70 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  uch changes will
33f80 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63   eventually.** c
33f90 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61  ommit if the tra
33fa0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75  nsaction continu
33fb0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
33fc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74  .)^.**.** ^Use t
33fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
33fe0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
33ff0 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ace to determine
34000 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
34010 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e  the opened blob.
34020 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61    ^The size of a
34030 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65   blob may not be
34040 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73   changed by this
34050 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20  .** interface.  
34060 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d  Use the [UPDATE]
34070 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20   SQL command to 
34080 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20  change the size 
34090 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a  of a.** blob..**
340a0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
340b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
340c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
340d0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
340e0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  )] interfaces.**
340f0 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69   and the built-i
34100 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c  n [zeroblob] SQL
34110 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65   function can be
34120 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65   used, if desire
34130 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20  d,.** to create 
34140 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66  an empty, zero-f
34150 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68  illed blob in wh
34160 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77  ich to read or w
34170 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68  rite using.** th
34180 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
34190 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72  .** To avoid a r
341a0 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76  esource leak, ev
341b0 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68  ery open [BLOB h
341c0 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76  andle] should ev
341d0 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72  entually.** be r
341e0 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c  eleased by a cal
341f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34200 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a  ob_close()]..*/.
34210 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
34220 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33  _open(.  sqlite3
34230 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  *,.  const char 
34240 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68  *zDb,.  const ch
34250 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f  ar *zTable,.  co
34260 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
34270 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  n,.  sqlite3_int
34280 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66  64 iRow,.  int f
34290 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lags,.  sqlite3_
342a0 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b  blob **ppBlob.);
342b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
342c0 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48  : Close A BLOB H
342d0 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  andle.**.** ^Clo
342e0 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  ses an open [BLO
342f0 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a  B handle]..**.**
34300 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42   ^Closing a BLOB
34310 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
34320 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
34330 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a  tion to commit.*
34340 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  * if there are n
34350 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e  o other BLOBs, n
34360 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72  o pending prepar
34370 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  ed statements, a
34380 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
34390 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
343a0 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20   in [autocommit 
343b0 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e  mode]..** ^If an
343c0 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61  y writes were ma
343d0 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20  de to the BLOB, 
343e0 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65  they might be he
343f0 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75  ld in cache.** u
34400 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f  ntil the close o
34410 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79  peration if they
34420 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a   will fit..**.**
34430 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42   ^(Closing the B
34440 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73  LOB often forces
34450 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20   the changes.** 
34460 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20  out to disk and 
34470 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72  so if any I/O er
34480 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79  rors occur, they
34490 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63   will likely occ
344a0 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d  ur.** at the tim
344b0 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  e when the BLOB 
344c0 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20  is closed.  Any 
344d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
344e0 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73  r during.** clos
344f0 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64  ing are reported
34500 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   as a non-zero r
34510 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a  eturn value.)^.*
34520 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20  *.** ^(The BLOB 
34530 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64  is closed uncond
34540 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e  itionally.  Even
34550 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   if this routine
34560 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65   returns.** an e
34570 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42  rror code, the B
34580 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f  LOB is still clo
34590 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61  sed.)^.**.** ^Ca
345a0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
345b0 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70  ne with a null p
345c0 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20  ointer (such as 
345d0 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  would be returne
345e0 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64  d.** by a failed
345f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34600 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20  3_blob_open()]) 
34610 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
34620 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
34630 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73  te3_blob_close(s
34640 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
34650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34660 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65   Return The Size
34670 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   Of An Open BLOB
34680 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20  .**.** ^Returns 
34690 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
346a0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63  s of the BLOB ac
346b0 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
346c0 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c   .** successfull
346d0 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68  y opened [BLOB h
346e0 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e  andle] in its on
346f0 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  ly argument.  ^T
34700 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61  he.** incrementa
34710 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69  l blob I/O routi
34720 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61  nes can only rea
34730 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67  d or overwriting
34740 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f   existing.** blo
34750 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20  b content; they 
34760 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
34770 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
34780 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
34790 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
347a0 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
347b0 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
347c0 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
347d0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
347e0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
347f0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
34800 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
34810 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
34820 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
34830 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
34840 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
34850 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
34860 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
34870 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
34880 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
34890 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
348a0 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  vior..*/.int sql
348b0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
348c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
348d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
348e0 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d  : Read Data From
348f0 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
34900 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tally.**.** ^(Th
34910 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
34920 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61  sed to read data
34930 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42   from an open [B
34940 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f  LOB handle] into
34950 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70   a.** caller-sup
34960 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20  plied buffer. N 
34970 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
34980 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75  e copied into bu
34990 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74  ffer Z.** from t
349a0 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74  he open BLOB, st
349b0 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74  arting at offset
349c0 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a   iOffset.)^.**.*
349d0 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66  * ^If offset iOf
349e0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
349f0 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
34a00 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
34a10 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
34a20 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
34a30 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
34a40 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72   read.  ^If N or
34a50 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c   iOffset is.** l
34a60 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b  ess than zero, [
34a70 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
34a80 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
34a90 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a   data is read..*
34aa0 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74  * ^The size of t
34ab0 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e  he blob (and hen
34ac0 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
34ad0 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
34ae0 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
34af0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
34b00 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
34b10 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
34b20 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
34b30 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72  tempt to read fr
34b40 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  om an expired [B
34b50 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
34b60 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
34b70 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
34b80 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
34b90 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73   ^(On success, s
34ba0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
34bb0 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
34bc0 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  E_OK..** Otherwi
34bd0 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  se, an [error co
34be0 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
34bf0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
34c00 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
34c10 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
34c20 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
34c30 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
34c40 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
34c50 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
34c60 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
34c70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34c80 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
34c90 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
34ca0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
34cb0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
34cc0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
34cd0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
34ce0 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
34cf0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
34d00 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
34d10 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
34d20 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
34d30 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
34d40 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  o: [sqlite3_blob
34d50 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  _write()]..*/.in
34d60 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  t sqlite3_blob_r
34d70 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ead(sqlite3_blob
34d80 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74   *, void *Z, int
34d90 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   N, int iOffset)
34da0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34db0 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e  F: Write Data In
34dc0 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d  to A BLOB Increm
34dd0 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54  entally.**.** ^T
34de0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
34df0 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61  used to write da
34e00 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20  ta into an open 
34e10 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72  [BLOB handle] fr
34e20 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73  om a.** caller-s
34e30 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20  upplied buffer. 
34e40 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61  ^N bytes of data
34e50 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d   are copied from
34e60 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a   the buffer Z.**
34e70 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42   into the open B
34e80 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
34e90 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
34ea0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
34eb0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73  BLOB handle] pas
34ec0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
34ed0 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f   argument was no
34ee0 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20  t opened for.** 
34ef0 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61  writing (the fla
34f00 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
34f10 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
34f20 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c  en()] was zero),
34f30 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
34f40 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  n returns [SQLIT
34f50 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a  E_READONLY]..**.
34f60 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
34f70 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66  n may only modif
34f80 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  y the contents o
34f90 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69  f the BLOB; it i
34fa0 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c  s.** not possibl
34fb0 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68  e to increase th
34fc0 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42  e size of a BLOB
34fd0 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e   using this API.
34fe0 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69  .** ^If offset i
34ff0 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
35000 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
35010 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
35020 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
35030 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
35040 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
35050 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66  is written.  ^If
35060 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
35070 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f  an zero [SQLITE_
35080 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
35090 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
350a0 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68  s written..** Th
350b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c  e size of the BL
350c0 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  OB (and hence th
350d0 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
350e0 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
350f0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
35100 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
35110 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
35120 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
35130 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74  *.** ^An attempt
35140 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20   to write to an 
35150 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61  expired [BLOB ha
35160 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68  ndle] fails with
35170 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64   an.** error cod
35180 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
35190 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f  RT].  ^Writes to
351a0 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f   the BLOB that o
351b0 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72  ccurred.** befor
351c0 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64  e the [BLOB hand
351d0 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20  le] expired are 
351e0 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  not rolled back 
351f0 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61  by the.** expira
35200 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64  tion of the hand
35210 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  le, though of co
35220 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67  urse those chang
35230 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65  es might.** have
35240 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65   been overwritte
35250 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  n by the stateme
35260 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20  nt that expired 
35270 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a  the BLOB handle.
35280 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69  ** or by other i
35290 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65  ndependent state
352a0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  ments..**.** ^(O
352b0 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74  n success, sqlit
352c0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20  e3_blob_write() 
352d0 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
352e0 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
352f0 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65   an  [error code
35300 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65  ] or an [extende
35310 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
35320 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
35330 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
35340 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
35350 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
35360 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
35370 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
35380 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
35390 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
353a0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
353b0 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
353c0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
353d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
353e0 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
353f0 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
35400 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
35410 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
35420 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
35430 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
35440 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
35450 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
35460 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
35470 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ead()]..*/.int s
35480 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
35490 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
354a0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c  , const void *z,
354b0 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66   int n, int iOff
354c0 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  set);../*.** CAP
354d0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46  I3REF: Virtual F
354e0 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63  ile System Objec
354f0 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75  ts.**.** A virtu
35500 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56  al filesystem (V
35510 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74  FS) is an [sqlit
35520 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a  e3_vfs] object.*
35530 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73  * that SQLite us
35540 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a  es to interact.*
35550 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72  * with the under
35560 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20  lying operating 
35570 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51  system.  Most SQ
35580 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65  Lite builds come
35590 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c   with a.** singl
355a0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68  e default VFS th
355b0 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  at is appropriat
355c0 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63  e for the host c
355d0 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20  omputer..** New 
355e0 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67  VFSes can be reg
355f0 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73  istered and exis
35600 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62  ting VFSes can b
35610 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a  e unregistered..
35620 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
35630 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
35640 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  provided..**.** 
35650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73  ^The sqlite3_vfs
35660 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63  _find() interfac
35670 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
35680 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76  ter to a VFS giv
35690 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20  en its name..** 
356a0 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20  ^Names are case 
356b0 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e  sensitive..** ^N
356c0 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65  ames are zero-te
356d0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
356e0 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74  trings..** ^If t
356f0 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68  here is no match
35700 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  , a NULL pointer
35710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
35720 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73   ^If zVfsName is
35730 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
35740 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65  efault VFS is re
35750 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  turned..**.** ^N
35760 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67  ew VFSes are reg
35770 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c  istered with sql
35780 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
35790 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65  r()..** ^Each ne
357a0 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68  w VFS becomes th
357b0 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66  e default VFS if
357c0 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c   the makeDflt fl
357d0 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54  ag is set..** ^T
357e0 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20  he same VFS can 
357f0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
35800 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  ltiple times wit
35810 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20  hout injury..** 
35820 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73  ^To make an exis
35830 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68  ting VFS into th
35840 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72  e default VFS, r
35850 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e  egister it again
35860 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b  .** with the mak
35870 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20  eDflt flag set. 
35880 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e   If two differen
35890 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65  t VFSes with the
358a0 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  .** same name ar
358b0 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68  e registered, th
358c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
358d0 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a  defined.  If a.*
358e0 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65  * VFS is registe
358f0 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20  red with a name 
35900 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20  that is NULL or 
35910 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
35920 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
35930 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
35940 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67  ed..**.** ^Unreg
35950 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68  ister a VFS with
35960 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
35970 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e  _unregister() in
35980 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66  terface..** ^(If
35990 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
359a0 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64   is unregistered
359b0 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73  , another VFS is
359c0 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68   chosen as.** th
359d0 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20  e default.  The 
359e0 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e  choice for the n
359f0 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72  ew VFS is arbitr
35a00 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65  ary.)^.*/.sqlite
35a10 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76  3_vfs *sqlite3_v
35a20 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68  fs_find(const ch
35a30 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69  ar *zVfsName);.i
35a40 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  nt sqlite3_vfs_r
35a50 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f  egister(sqlite3_
35a60 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66  vfs*, int makeDf
35a70 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  lt);.int sqlite3
35a80 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
35a90 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a  sqlite3_vfs*);..
35aa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35ab0 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Mutexes.**.** Th
35ac0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
35ad0 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
35ae0 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20  s for thread.** 
35af0 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e  synchronization.
35b00 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65   Though they are
35b10 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e   intended for in
35b20 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79  ternal.** use by
35b30 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68   SQLite, code th
35b40 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
35b50 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65   SQLite is.** pe
35b60 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61  rmitted to use a
35b70 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
35b80 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
35b90 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
35ba0 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74  de contains mult
35bb0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
35bc0 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65  ions.** of these
35bd0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
35be0 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65    An appropriate
35bf0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
35c00 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61  ** is selected a
35c10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20  utomatically at 
35c20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e  compile-time.  ^
35c30 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  (The following.*
35c40 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
35c50 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
35c60 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  in the SQLite co
35c70 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  re:.**.** <ul>.*
35c80 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
35c90 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69  MUTEX_OS2.** <li
35ca0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
35cb0 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e  _PTHREAD.** <li>
35cc0 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
35cd0 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  W32.** <li>   SQ
35ce0 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a  LITE_MUTEX_NOOP.
35cf0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
35d00 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54   ^The SQLITE_MUT
35d10 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e  EX_NOOP implemen
35d20 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20  tation is a set 
35d30 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74  of routines.** t
35d40 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c  hat does no real
35d50 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20   locking and is 
35d60 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20  appropriate for 
35d70 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67  use in.** a sing
35d80 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  le-threaded appl
35d90 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53  ication.  ^The S
35da0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
35db0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
35dc0 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
35dd0 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
35de0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
35df0 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
35e00 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f  e for use on OS/
35e10 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e  2, Unix, and Win
35e20 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  dows..**.** ^(If
35e30 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
35e40 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
35e50 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
35e60 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a   preprocessor.**
35e70 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28   macro defined (
35e80 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d  with "-DSQLITE_M
35e90 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c  UTEX_APPDEF=1"),
35ea0 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a   then no mutex.*
35eb0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
35ec0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74   is included wit
35ed0 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49  h the library. I
35ee0 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a  n this case the.
35ef0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  ** application m
35f00 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73  ust supply a cus
35f10 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  tom mutex implem
35f20 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74  entation using t
35f30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
35f40 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69  NFIG_MUTEX] opti
35f50 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  on of the sqlite
35f60 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74  3_config() funct
35f70 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61  ion.** before ca
35f80 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e  lling sqlite3_in
35f90 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e  itialize() or an
35fa0 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73  y other public s
35fb0 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74  qlite3_.** funct
35fc0 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73  ion that calls s
35fd0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
35fe0 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  e().)^.**.** ^Th
35ff0 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
36000 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
36010 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a  allocates a new.
36020 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74  ** mutex and ret
36030 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
36040 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74  o it. ^If it ret
36050 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61  urns NULL.** tha
36060 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d  t means that a m
36070 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62  utex could not b
36080 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53  e allocated.  ^S
36090 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e  QLite.** will un
360a0 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61  wind its stack a
360b0 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  nd return an err
360c0 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  or.  ^(The argum
360d0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
360e0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
360f0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  is one of these 
36100 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
36110 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
36120 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
36130 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e  TEX_FAST.** <li>
36140 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52    SQLITE_MUTEX_R
36150 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  ECURSIVE.** <li>
36160 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
36170 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20  TATIC_MASTER.** 
36180 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36190 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a  EX_STATIC_MEM.**
361a0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
361b0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a  TEX_STATIC_MEM2.
361c0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
361d0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
361e0 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  G.** <li>  SQLIT
361f0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
36200 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  RU.** <li>  SQLI
36210 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
36220 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  LRU2.** </ul>)^.
36230 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
36240 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28   two constants (
36250 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
36260 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  T and SQLITE_MUT
36270 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a  EX_RECURSIVE).**
36280 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d   cause sqlite3_m
36290 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20  utex_alloc() to 
362a0 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20  create.** a new 
362b0 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77  mutex.  ^The new
362c0 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73   mutex is recurs
362d0 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ive when SQLITE_
362e0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a  MUTEX_RECURSIVE.
362f0 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e  ** is used but n
36300 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73  ot necessarily s
36310 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  o when SQLITE_MU
36320 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64  TEX_FAST is used
36330 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69  ..** The mutex i
36340 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
36350 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d  es not need to m
36360 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f  ake a distinctio
36370 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
36380 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
36390 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d  IVE and SQLITE_M
363a0 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20  UTEX_FAST if it 
363b0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74  does.** not want
363c0 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69   to.  ^SQLite wi
363d0 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20  ll only request 
363e0 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  a recursive mute
363f0 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68  x in.** cases wh
36400 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65  ere it really ne
36410 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20  eds one.  ^If a 
36420 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72  faster non-recur
36430 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  sive mutex.** im
36440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
36450 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65  available on the
36460 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20   host platform, 
36470 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73  the mutex subsys
36480 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74  tem.** might ret
36490 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78  urn such a mutex
364a0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
364b0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
364c0 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74  T..**.** ^The ot
364d0 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61  her allowed para
364e0 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65  meters to sqlite
364f0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
36500 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a  (anything other.
36510 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d  ** than SQLITE_M
36520 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51  UTEX_FAST and SQ
36530 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
36540 53 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72  SIVE) each retur
36550 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  n.** a pointer t
36560 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78  o a static preex
36570 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e  isting mutex.  ^
36580 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78  Six static mutex
36590 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62  es are.** used b
365a0 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65  y the current ve
365b0 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e  rsion of SQLite.
365c0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
365d0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
365e0 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ay add additiona
365f0 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  l static mutexes
36600 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65  .  Static mutexe
36610 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e  s are for intern
36620 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c  al.** use by SQL
36630 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ite only.  Appli
36640 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
36650 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20   SQLite mutexes 
36660 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e  should.** use on
36670 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d  ly the dynamic m
36680 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20  utexes returned 
36690 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  by SQLITE_MUTEX_
366a0 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54  FAST or.** SQLIT
366b0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
366c0 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  E..**.** ^Note t
366d0 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68  hat if one of th
366e0 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  e dynamic mutex 
366f0 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49  parameters (SQLI
36700 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
36710 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   or SQLITE_MUTEX
36720 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75  _RECURSIVE) is u
36730 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33  sed then sqlite3
36740 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a  _mutex_alloc().*
36750 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66  * returns a diff
36760 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65  erent mutex on e
36770 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74  very call.  ^But
36780 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a   for the static.
36790 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20  ** mutex types, 
367a0 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69  the same mutex i
367b0 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76  s returned on ev
367c0 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61  ery call that ha
367d0 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79  s.** the same ty
367e0 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  pe number..**.**
367f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
36800 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69  tex_free() routi
36810 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ne deallocates a
36820 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61   previously.** a
36830 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63  llocated dynamic
36840 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65   mutex.  ^SQLite
36850 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64   is careful to d
36860 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a  eallocate every.
36870 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ** dynamic mutex
36880 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74   that it allocat
36890 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63  es.  The dynamic
368a0 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f   mutexes must no
368b0 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77  t be in.** use w
368c0 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61  hen they are dea
368d0 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d  llocated.  Attem
368e0 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63  pting to dealloc
368f0 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20  ate a static.** 
36900 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e  mutex results in
36910 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
36920 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65  ior.  ^SQLite ne
36930 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
36940 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
36950 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  x..**.** ^The sq
36960 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
36970 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
36980 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74  mutex_try() rout
36990 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ines attempt.** 
369a0 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78  to enter a mutex
369b0 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74  .  ^If another t
369c0 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79  hread is already
369d0 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65   within the mute
369e0 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  x,.** sqlite3_mu
369f0 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c  tex_enter() will
36a00 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74   block and sqlit
36a10 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77  e3_mutex_try() w
36a20 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  ill return.** SQ
36a30 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65  LITE_BUSY.  ^The
36a40 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
36a50 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ry() interface r
36a60 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
36a70 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65  K].** upon succe
36a80 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28  ssful entry.  ^(
36a90 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20  Mutexes created 
36aa0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
36ab0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
36ac0 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d  can be entered m
36ad0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79  ultiple times by
36ae0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
36af0 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73  ..** In such cas
36b00 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78  es the,.** mutex
36b10 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20   must be exited 
36b20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20  an equal number 
36b30 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20  of times before 
36b40 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
36b50 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20  * can enter.)^  
36b60 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68  ^(If the same th
36b70 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e  read tries to en
36b80 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  ter any other.**
36b90 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d   kind of mutex m
36ba0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74  ore than once, t
36bb0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
36bc0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c  ndefined..** SQL
36bd0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65  ite will never e
36be0 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62  xhibit.** such b
36bf0 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f  ehavior in its o
36c00 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65  wn use of mutexe
36c10 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d  s.)^.**.** ^(Som
36c20 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65  e systems (for e
36c30 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20  xample, Windows 
36c40 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  95) do not suppo
36c50 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  rt the operation
36c60 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  .** implemented 
36c70 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  by sqlite3_mutex
36c80 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73  _try().  On thos
36c90 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74  e systems, sqlit
36ca0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a  e3_mutex_try().*
36cb0 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  * will always re
36cc0 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59  turn SQLITE_BUSY
36cd0 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
36ce0 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65  re only ever use
36cf0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  s.** sqlite3_mut
36d00 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f  ex_try() as an o
36d10 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74  ptimization so t
36d20 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c  his is acceptabl
36d30 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a  e behavior.)^.**
36d40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36d50 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72  _mutex_leave() r
36d60 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d  outine exits a m
36d70 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a  utex that was.**
36d80 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65   previously ente
36d90 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20  red by the same 
36da0 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20  thread.   ^(The 
36db0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
36dc0 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20  ndefined if the 
36dd0 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72  mutex is not cur
36de0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62  rently entered b
36df0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67  y the.** calling
36e00 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f   thread or is no
36e10 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f  t currently allo
36e20 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77  cated.  SQLite w
36e30 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20  ill.** never do 
36e40 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  either.)^.**.** 
36e50 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
36e60 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   to sqlite3_mute
36e70 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74  x_enter(), sqlit
36e80 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20  e3_mutex_try(), 
36e90 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  or.** sqlite3_mu
36ea0 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61  tex_leave() is a
36eb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
36ec0 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f  hen all three ro
36ed0 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65  utines.** behave
36ee0 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   as no-ops..**.*
36ef0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
36f00 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
36f10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36f20 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
36f30 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74  ..*/.sqlite3_mut
36f40 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65  ex *sqlite3_mute
36f50 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  x_alloc(int);.vo
36f60 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
36f70 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75  _free(sqlite3_mu
36f80 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
36f90 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
36fa0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
36fb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
36fc0 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d  ex_try(sqlite3_m
36fd0 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
36fe0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
36ff0 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
37000 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37010 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73  F: Mutex Methods
37020 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
37030 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
37040 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69  s structure defi
37050 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65  nes the low-leve
37060 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73  l routines.** us
37070 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  ed to allocate a
37080 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a  nd use mutexes..
37090 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74  **.** Usually, t
370a0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
370b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
370c0 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c   provided by SQL
370d0 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69  ite are.** suffi
370e0 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74  cient, however t
370f0 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20  he user has the 
37100 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69  option of substi
37110 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a  tuting a custom.
37120 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
37130 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65  n for specialize
37140 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72  d deployments or
37150 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69   systems for whi
37160 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65  ch SQLite.** doe
37170 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20  s not provide a 
37180 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
37190 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73  ntation. In this
371a0 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a   case, the user.
371b0 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70  ** creates and p
371c0 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74  opulates an inst
371d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
371e0 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a  ucture to pass.*
371f0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  * to sqlite3_con
37200 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68  fig() along with
37210 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
37220 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
37230 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  n..** Additional
37240 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ly, an instance 
37250 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
37260 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  e can be used as
37270 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61   an.** output va
37280 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72  riable when quer
37290 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20  ying the system 
372a0 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
372b0 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
372c0 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74  ntation, using t
372d0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
372e0 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69  G_GETMUTEX] opti
372f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  on..**.** ^The x
37300 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
37310 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
37320 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e   structure is in
37330 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  voked as.** part
37340 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69   of system initi
37350 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65  alization by the
37360 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
37370 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a  ize() function..
37380 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e  ** ^The xMutexIn
37390 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  it routine is ca
373a0 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78  lle by SQLite ex
373b0 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65  actly once for e
373c0 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65  ach.** effective
373d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
373e0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e  3_initialize()].
373f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74  .**.** ^The xMut
37400 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66  exEnd method def
37410 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
37420 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65  ucture is invoke
37430 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
37440 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20  system shutdown 
37450 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
37460 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69  hutdown() functi
37470 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65  on. The.** imple
37480 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69  mentation of thi
37490 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65  s method is expe
374a0 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20  cted to release 
374b0 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a  all outstanding.
374c0 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74  ** resources obt
374d0 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74  ained by the mut
374e0 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65  ex methods imple
374f0 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63  mentation, espec
37500 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f  ially.** those o
37510 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78  btained by the x
37520 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
37530 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e  .  ^The xMutexEn
37540 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
37550 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63   is invoked exac
37560 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  tly once for eac
37570 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
37580 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
37590 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61  **.** ^(The rema
375a0 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68  ining seven meth
375b0 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74  ods defined by t
375c0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78  his structure (x
375d0 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78  MutexAlloc,.** x
375e0 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65  MutexFree, xMute
375f0 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72  xEnter, xMutexTr
37600 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20  y, xMutexLeave, 
37610 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a  xMutexHeld and.*
37620 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29  * xMutexNotheld)
37630 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66   implement the f
37640 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61  ollowing interfa
37650 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c  ces (respectivel
37660 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y):.**.** <ul>.*
37670 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
37680 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
37690 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
376a0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
376b0 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a  x_free()] </li>.
376c0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
376d0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
376e0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
376f0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
37700 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a  ex_try()] </li>.
37710 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
37720 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
37730 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
37740 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
37750 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  ex_held()] </li>
37760 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
37770 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
37780 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  ld()] </li>.** <
37790 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
377a0 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
377b0 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62   is that the pub
377c0 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20  lic sqlite3_XXX 
377d0 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72  functions enumer
377e0 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69  ated.** above si
377f0 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e  lently ignore an
37800 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68  y invocations th
37810 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70  at pass a NULL p
37820 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a  ointer instead.*
37830 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74  * of a valid mut
37840 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69  ex handle. The i
37850 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37860 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65  f the methods de
37870 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73  fined.** by this
37880 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e   structure are n
37890 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68  ot required to h
378a0 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c  andle this case,
378b0 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20   the results.** 
378c0 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c  of passing a NUL
378d0 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  L pointer instea
378e0 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74  d of a valid mut
378f0 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e  ex handle are un
37900 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e  defined.** (i.e.
37910 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c   it is acceptabl
37920 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20  e to provide an 
37930 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
37940 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66  hat segfaults if
37950 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64  .** it is passed
37960 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29   a NULL pointer)
37970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74  ..**.** The xMut
37980 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20  exInit() method 
37990 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
379a0 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65  fe.  ^It must be
379b0 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20   harmless to.** 
379c0 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69  invoke xMutexIni
379d0 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65  t() mutiple time
379e0 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
379f0 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69  e process and wi
37a00 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65  thout.** interve
37a10 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d  ning calls to xM
37a20 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f  utexEnd().  Seco
37a30 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
37a40 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d  t calls to.** xM
37a50 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20  utexInit() must 
37a60 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  be no-ops..**.**
37a70 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d   ^xMutexInit() m
37a80 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69  ust not use SQLi
37a90 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  te memory alloca
37aa0 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d  tion ([sqlite3_m
37ab0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20  alloc()].** and 
37ac0 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e  its associates).
37ad0 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d    ^Similarly, xM
37ae0 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74  utexAlloc() must
37af0 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
37b00 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
37b10 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69  tion for a stati
37b20 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76  c mutex.  ^Howev
37b30 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29  er xMutexAlloc()
37b40 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a   may use SQLite.
37b50 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
37b60 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20  tion for a fast 
37b70 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74  or recursive mut
37b80 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ex..**.** ^SQLit
37b90 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
37ba0 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65  e xMutexEnd() me
37bb0 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  thod when [sqlit
37bc0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69  e3_shutdown()] i
37bd0 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74  s.** called, but
37be0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69   only if the pri
37bf0 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65  or call to xMute
37c00 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53  xInit returned S
37c10 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20  QLITE_OK..** If 
37c20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73  xMutexInit fails
37c30 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20   in any way, it 
37c40 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63  is expected to c
37c50 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74  lean up after it
37c60 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  self.** prior to
37c70 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74   returning..*/.t
37c80 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
37c90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
37ca0 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  ods sqlite3_mute
37cb0 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  x_methods;.struc
37cc0 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
37cd0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
37ce0 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f  (*xMutexInit)(vo
37cf0 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  id);.  int (*xMu
37d00 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20  texEnd)(void);. 
37d10 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a   sqlite3_mutex *
37d20 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69  (*xMutexAlloc)(i
37d30 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d  nt);.  void (*xM
37d40 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65  utexFree)(sqlite
37d50 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f  3_mutex *);.  vo
37d60 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72  id (*xMutexEnter
37d70 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
37d80 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
37d90 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d  exTry)(sqlite3_m
37da0 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
37db0 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73  (*xMutexLeave)(s
37dc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
37dd0 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48  .  int (*xMutexH
37de0 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  eld)(sqlite3_mut
37df0 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ex *);.  int (*x
37e00 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71  MutexNotheld)(sq
37e10 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
37e20 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
37e30 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69  EF: Mutex Verifi
37e40 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
37e50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
37e60 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61  3_mutex_held() a
37e70 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
37e80 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69  _notheld() routi
37e90 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e  nes.** are inten
37ea0 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ded for use insi
37eb0 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74  de assert() stat
37ec0 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51  ements.  ^The SQ
37ed0 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76  Lite core.** nev
37ee0 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  er uses these ro
37ef0 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e  utines except in
37f00 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29  side an assert()
37f10 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e   and application
37f20 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64  s.** are advised
37f30 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c   to follow the l
37f40 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e  ead of the core.
37f50 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f    ^The SQLite co
37f60 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69  re only.** provi
37f70 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  des implementati
37f80 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f  ons for these ro
37f90 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69  utines when it i
37fa0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
37fb0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45  th the SQLITE_DE
37fc0 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65  BUG flag.  ^Exte
37fd0 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65  rnal mutex imple
37fe0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
37ff0 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20  e only required 
38000 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65  to provide these
38010 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c   routines if SQL
38020 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20  ITE_DEBUG is.** 
38030 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e  defined and if N
38040 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66  DEBUG is not def
38050 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
38060 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  se routines shou
38070 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69  ld return true i
38080 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74  f the mutex in t
38090 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  heir argument.**
380a0 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20   is held or not 
380b0 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65  held, respective
380c0 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69  ly, by the calli
380d0 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a  ng thread..**.**
380e0 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
380f0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75  tion is not requ
38100 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64  ired to provided
38110 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
38120 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  se.** routines t
38130 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72  hat actually wor
38140 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d  k. If the implem
38150 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
38160 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e  t provide workin
38170 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  g.** versions of
38180 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
38190 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65   it should at le
381a0 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62  ast provide stub
381b0 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a  s that always.**
381c0 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20   return true so 
381d0 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f  that one does no
381e0 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61  t get spurious a
381f0 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65  ssertion failure
38200 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
38210 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
38220 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
38230 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
38240 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ter then.** the 
38250 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72  routine should r
38260 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20  eturn 1.   This 
38270 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e  seems counter-in
38280 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a  tuitive since.**
38290 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74   clearly the mut
382a0 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c  ex cannot be hel
382b0 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74  d if it does not
382c0 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65   exist.  But the
382d0 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74  .** the reason t
382e0 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f  he mutex does no
382f0 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75  t exist is becau
38300 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20  se the build is 
38310 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74  not.** using mut
38320 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f  exes.  And we do
38330 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73   not want the as
38340 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e  sert() containin
38350 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f  g the.** call to
38360 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68   sqlite3_mutex_h
38370 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73  eld() to fail, s
38380 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  o a non-zero ret
38390 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70  urn is.** the ap
383a0 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20  propriate thing 
383b0 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c  to do.  ^The sql
383c0 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
383d0 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ld().** interfac
383e0 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65  e should also re
383f0 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65  turn 1 when give
38400 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
38410 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45  ..*/.#ifndef NDE
38420 42 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  BUG.int sqlite3_
38430 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74  mutex_held(sqlit
38440 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
38450 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
38460 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  theld(sqlite3_mu
38470 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  tex*);.#endif../
38480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
38490 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a  utex Types.**.**
384a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   The [sqlite3_mu
384b0 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74  tex_alloc()] int
384c0 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73  erface takes a s
384d0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
384e0 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f  * which is one o
384f0 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
38500 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
38510 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74   The set of stat
38520 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63  ic mutexes may c
38530 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53  hange from one S
38540 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f  QLite release to
38550 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
38560 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
38570 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75   override the bu
38580 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67  ilt-in mutex log
38590 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72  ic must be.** pr
385a0 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d  epared to accomm
385b0 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c  odate additional
385c0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
385d0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
385e0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20  TE_MUTEX_FAST   
385f0 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
38600 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
38610 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20  _RECURSIVE      
38620 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
38630 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
38640 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66  MASTER    2.#def
38650 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
38660 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20  _STATIC_MEM     
38670 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    3  /* sqlite3_
38680 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66  malloc() */.#def
38690 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
386a0 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20  _STATIC_MEM2    
386b0 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44    4  /* NOT USED
386c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
386d0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
386e0 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20  OPEN      4  /* 
386f0 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e  sqlite3BtreeOpen
38700 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
38710 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
38720 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f  C_PRNG      5  /
38730 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  * sqlite3_random
38740 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
38750 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
38760 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f  C_LRU       6  /
38770 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20  * lru page list 
38780 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38790 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
387a0 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c  RU2      7  /* l
387b0 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a  ru page list */.
387c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
387d0 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75   Retrieve the mu
387e0 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61  tex for a databa
387f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
38800 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
38810 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
38820 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74  inter the [sqlit
38830 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
38840 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c   that .** serial
38850 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74  izes access to t
38860 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
38870 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69  nection] given i
38880 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  n the argument.*
38890 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65  * when the [thre
388a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53  ading mode] is S
388b0 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49  erialized..** ^I
388c0 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  f the [threading
388d0 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65   mode] is Single
388e0 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69