/ Hex Artifact Content
Login

Artifact aa9086ea3a365843d62ce120cba458ecad6edd63:


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 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7390: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
73a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
73b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4f 70 65 6e    int (*xShmOpen
73c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
73d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 53 69  ;.  int (*xShmSi
73e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
73f0: 2a 2c 20 69 6e 74 20 72 65 71 53 69 7a 65 2c 20  *, int reqSize, 
7400: 69 6e 74 20 2a 70 4e 65 77 53 69 7a 65 29 3b 0a  int *pNewSize);.
7410: 20 20 69 6e 74 20 28 2a 78 53 68 6d 47 65 74 29    int (*xShmGet)
7420: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7430: 69 6e 74 20 72 65 71 53 69 7a 65 2c 20 69 6e 74  int reqSize, int
7440: 20 2a 70 53 69 7a 65 2c 20 76 6f 69 64 20 76 6f   *pSize, void vo
7450: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
7460: 20 28 2a 78 53 68 6d 52 65 6c 65 61 73 65 29 28   (*xShmRelease)(
7470: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7480: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
7490: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
74a0: 20 69 6e 74 20 64 65 73 69 72 65 64 4c 6f 63 6b   int desiredLock
74b0: 2c 20 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 29 3b  , int *gotLock);
74c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c 6f  .  int (*xShmClo
74d0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
74e0: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
74f0: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
7500: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
7510: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
7520: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
7530: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
7540: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
7550: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
7560: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7570: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
7580: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
7590: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
75a0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
75b0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
75c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
75d0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
75e0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
75f0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7600: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7610: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7620: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7630: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
7640: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
7650: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
7660: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
7670: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
7680: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
7690: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
76a0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
76b0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
76c0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
76d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
76e0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
76f0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7700: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7710: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7720: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7730: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7740: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
7750: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
7760: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
7770: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
7780: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
7790: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
77a0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
77b0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
77c0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
77d0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
77e0: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
77f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7800: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7820: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7830: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
7840: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
7850: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
7860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7870: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
7880: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
7890: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
78a0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
78b0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
78c0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
78d0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
78e0: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
78f0: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7900: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7910: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7920: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7930: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
7940: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
7950: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
7960: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
7970: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
7980: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
7990: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
79a0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
79b0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
79c0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
79d0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
79e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
79f0: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7a00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7a10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7a20: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7a30: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
7a40: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
7a50: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
7a60: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
7a70: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
7a80: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
7a90: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7aa0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7ab0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7ac0: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7ad0: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7ae0: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7af0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7b00: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7b10: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7b20: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7b30: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
7b40: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
7b50: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
7b60: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
7b70: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
7b80: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
7b90: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7ba0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7bb0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7bc0: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7bd0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7be0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7bf0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7c00: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7c10: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7c20: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7c30: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7c40: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7c50: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7c60: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7c70: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7c80: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7c90: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7ca0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7cb0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7cc0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7cd0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7ce0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7cf0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7d00: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7d10: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7d20: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7d30: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7d40: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7d50: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7d60: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7d70: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7d80: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7d90: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7da0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7db0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7dc0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7dd0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7de0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7df0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7e00: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7e10: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7e20: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7e30: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7e40: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7e50: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7e60: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7e70: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7e80: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7e90: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7ea0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7eb0: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7ec0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7ed0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7ee0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7ef0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7f00: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7f10: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7f20: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7f30: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7f40: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7f50: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7f60: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7f70: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7f80: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7f90: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7fa0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7fb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7fc0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7fd0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7fe0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7ff0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
8000: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
8010: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
8020: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
8030: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
8040: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
8050: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
8060: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
8070: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
8080: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
8090: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
80a0: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
80b0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
80c0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
80d0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
80e0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
80f0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
8100: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
8110: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
8120: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
8130: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
8140: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
8150: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
8160: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
8170: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
8180: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
8190: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
81a0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
81b0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
81c0: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
81d0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
81e0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
81f0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8200: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8210: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8220: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8230: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
8240: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
8250: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
8260: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
8270: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
8280: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
8290: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
82a0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
82b0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
82c0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
82d0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
82e0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
82f0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8300: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8310: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8320: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8330: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
8340: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
8350: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
8360: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
8370: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
8380: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
8390: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
83a0: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
83b0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
83c0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
83d0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
83e0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
83f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8400: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8410: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8420: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8430: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
8440: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
8450: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
8460: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
8470: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
8480: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
8490: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
84a0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
84b0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
84c0: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
84d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
84e0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
84f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8500: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8510: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8520: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8530: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
8540: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
8550: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
8560: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
8570: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8580: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
8590: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
85a0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
85b0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
85c0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
85d0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
85e0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
85f0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8600: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8610: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8620: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8630: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
8640: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
8650: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
8660: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
8670: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
8680: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
8690: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
86a0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
86b0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
86c0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
86d0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
86e0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
86f0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8700: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8710: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8720: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8730: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
8740: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
8750: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
8760: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
8770: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
8780: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
8790: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
87a0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
87b0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
87c0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
87d0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
87e0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
87f0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8800: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8810: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8820: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8830: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
8840: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
8850: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
8860: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
8870: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
8880: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
8890: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
88a0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
88b0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
88c0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
88d0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
88e0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
88f0: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8900: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8910: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8920: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8930: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
8940: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
8950: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
8960: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
8970: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
8980: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
8990: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
89a0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
89b0: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
89c0: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
89d0: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
89e0: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
89f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8a00: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8a10: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8a20: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8a30: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
8a40: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
8a50: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
8a60: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
8a70: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
8a80: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
8a90: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8aa0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8ab0: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8ac0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8ad0: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8ae0: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8af0: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8b00: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8b10: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8b20: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8b30: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
8b40: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
8b50: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
8b60: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
8b70: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
8b80: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
8b90: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8ba0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8bb0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8bc0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8bd0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8be0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8bf0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8c00: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8c10: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8c20: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8c30: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8c40: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8c50: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8c60: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8c70: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8c80: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8c90: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8ca0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8cb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8cc0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8cd0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8ce0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8cf0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8d00: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8d10: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8d20: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8d30: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8d40: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8d50: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8d60: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8d70: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8d80: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8d90: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8da0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8db0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8dc0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8dd0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8de0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8df0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8e00: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8e10: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8e20: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8e30: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8e40: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8e50: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8e60: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8e70: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8e80: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8e90: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8ea0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8eb0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8ec0: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8ed0: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8ee0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8ef0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8f00: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8f10: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8f20: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8f30: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8f40: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8f50: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8f60: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8f70: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8f80: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8f90: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8fa0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8fb0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8fc0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8fd0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8fe0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8ff0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
9000: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
9010: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
9020: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
9030: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
9040: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
9050: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
9060: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
9070: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
9080: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
9090: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
90a0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
90b0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
90c0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
90d0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
90e0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
90f0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
9100: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
9110: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
9120: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
9130: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
9140: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
9150: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
9160: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
9170: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
9180: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
9190: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
91a0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
91b0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
91c0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
91d0: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
91e0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
91f0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9200: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9210: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9220: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9230: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
9240: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9250: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
9260: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9270: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
9280: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
9290: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
92a0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
92b0: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
92c0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
92d0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
92e0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
92f0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
9300: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
9310: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
9320: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
9330: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
9340: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
9350: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
9360: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
9370: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
9380: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
9390: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
93a0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
93b0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
93c0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
93d0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
93e0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
93f0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
9400: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
9410: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9420: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
9430: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
9440: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
9450: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
9460: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
9470: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
9480: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9490: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
94a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
94b0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
94c0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
94d0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
94e0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
94f0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
9500: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
9510: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9520: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
9530: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9540: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
9550: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9560: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
9570: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
9580: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
9590: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
95a0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
95b0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
95c0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
95d0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
95e0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
95f0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
9600: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
9610: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
9620: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
9630: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9640: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
9650: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
9660: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
9670: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
9680: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
9690: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
96a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
96b0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
96c0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
96d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
96e0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
96f0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
9700: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
9710: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
9720: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9730: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
9740: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
9750: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
9760: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
9770: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
9780: 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c  t (*xRename)(sql
9790: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
97a0: 20 63 68 61 72 20 2a 7a 4f 6c 64 2c 20 63 6f 6e   char *zOld, con
97b0: 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 2c 20 69  st char *zNew, i
97c0: 6e 74 20 64 69 72 53 79 6e 63 29 3b 0a 20 20 69  nt dirSync);.  i
97d0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
97e0: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
97f0: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
9800: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
9810: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
9820: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
9830: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
9840: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
9850: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
9860: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
9870: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
9880: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
9890: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
98a0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
98b0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
98c0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
98d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
98e0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
98f0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
9900: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
9910: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
9920: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
9930: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
9940: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
9950: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
9960: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
9970: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
9980: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
9990: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
99a0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
99b0: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
99c0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
99d0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
99e0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
99f0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
9a00: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
9a10: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
9a20: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
9a30: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9a40: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
9a50: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
9a60: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
9a70: 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  e is both readab
9a80: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e  le and writable.
9a90: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9aa0: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
9ab0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
9ac0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
9ad0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
9ae0: 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69  adable..*/.#defi
9af0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9b00: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
9b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9b20: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23  SS_READWRITE 1.#
9b30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9b40: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
9b50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9b60: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
9b70: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
9b80: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
9b90: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
9ba0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
9bb0: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 73 74 61  ious locking sta
9bc0: 74 65 73 20 74 68 61 74 0a 2a 2a 20 61 6e 20 73  tes that.** an s
9bd0: 71 6c 69 74 65 33 5f 73 68 6d 20 6f 62 6a 65 63  qlite3_shm objec
9be0: 74 20 63 61 6e 20 62 65 20 69 6e 2e 0a 2a 2f 0a  t can be in..*/.
9bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9c00: 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
9c10: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
9c20: 5f 53 48 4d 5f 52 45 41 44 20 20 20 20 20 20 20  _SHM_READ       
9c30: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
9c40: 54 45 5f 53 48 4d 5f 52 45 41 44 5f 46 55 4c 4c  TE_SHM_READ_FULL
9c50: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
9c60: 4c 49 54 45 5f 53 48 4d 5f 57 52 49 54 45 20 20  LITE_SHM_WRITE  
9c70: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
9c80: 53 51 4c 49 54 45 5f 53 48 4d 5f 50 45 4e 44 49  SQLITE_SHM_PENDI
9c90: 4e 47 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  NG      4.#defin
9ca0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 43 48 45  e SQLITE_SHM_CHE
9cb0: 43 4b 50 4f 49 4e 54 20 20 20 35 0a 23 64 65 66  CKPOINT   5.#def
9cc0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52  ine SQLITE_SHM_R
9cd0: 45 43 4f 56 45 52 20 20 20 20 20 20 36 0a 0a 2f  ECOVER      6../
9ce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
9cf0: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
9d00: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
9d10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
9d20: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
9d30: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
9d40: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
9d50: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
9d60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9d70: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
9d80: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
9d90: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
9da0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
9db0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9dc0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
9dd0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
9de0: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
9df0: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
9e00: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
9e10: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
9e20: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
9e30: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
9e40: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
9e50: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
9e60: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
9e70: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
9e80: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
9e90: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
9ea0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9eb0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
9ec0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
9ed0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
9ee0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9ef0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
9f00: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
9f10: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
9f20: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
9f30: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
9f40: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
9f50: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
9f60: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
9f70: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
9f80: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9f90: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
9fa0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
9fb0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9fc0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
9fd0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
9fe0: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
9ff0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
a000: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
a010: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
a020: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
a030: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
a040: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
a050: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
a060: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a070: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
a080: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
a090: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
a0a0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
a0b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
a0c0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
a0d0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
a0e0: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
a0f0: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
a100: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a110: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
a120: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
a130: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
a140: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
a150: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
a160: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
a170: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
a180: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
a190: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
a1a0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
a1b0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
a1c0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
a1d0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
a1e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a1f0: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
a200: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
a210: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
a220: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
a230: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
a240: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
a250: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a260: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
a270: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
a280: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a290: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
a2a0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a2b0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
a2c0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
a2d0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
a2e0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
a2f0: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
a300: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a310: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
a320: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a330: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
a340: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
a350: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
a360: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
a370: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
a380: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
a390: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
a3a0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
a3b0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
a3c0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
a3d0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
a3e0: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
a3f0: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
a400: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
a410: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
a420: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
a430: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
a440: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
a450: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
a460: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
a470: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
a480: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
a490: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
a4a0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
a4b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
a4c0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
a4d0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
a4e0: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
a4f0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a500: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
a510: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
a520: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
a530: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
a540: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
a550: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
a560: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
a570: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
a580: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
a590: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
a5a0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
a5b0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
a5c0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
a5d0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
a5e0: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
a5f0: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
a600: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a610: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
a620: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
a630: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
a640: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a650: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
a660: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
a670: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
a680: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
a690: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
a6a0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
a6b0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
a6c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
a6d0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
a6e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
a6f0: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
a700: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
a710: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
a720: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
a730: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
a740: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
a750: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
a760: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
a770: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
a780: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
a790: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
a7a0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
a7b0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
a7c0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
a7d0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
a7e0: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
a7f0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
a800: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
a810: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
a820: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
a830: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
a840: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
a850: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
a860: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
a870: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a880: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
a890: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
a8a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
a8b0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
a8c0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
a8d0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
a8e0: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
a8f0: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
a900: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
a910: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
a920: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
a930: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
a940: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
a950: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
a960: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
a970: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
a980: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a990: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
a9a0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
a9b0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
a9c0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
a9d0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
a9e0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a9f0: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
aa00: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
aa10: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
aa20: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
aa30: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
aa40: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
aa50: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
aa60: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
aa70: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
aa80: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
aa90: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
aaa0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
aab0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
aac0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
aad0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
aae0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
aaf0: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
ab00: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
ab10: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
ab20: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
ab30: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
ab40: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
ab50: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
ab60: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
ab70: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
ab80: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
ab90: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
aba0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
abb0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
abc0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
abd0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
abe0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
abf0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
ac00: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
ac10: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
ac20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
ac30: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
ac40: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
ac50: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
ac60: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
ac70: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
ac80: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
ac90: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
aca0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
acb0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
acc0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
acd0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
ace0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
acf0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
ad00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
ad10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
ad20: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
ad30: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
ad40: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
ad50: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
ad60: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
ad70: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
ad80: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
ad90: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
ada0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
adb0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
adc0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
add0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
ade0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
adf0: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
ae00: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
ae10: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
ae20: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
ae30: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
ae40: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
ae50: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
ae60: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
ae70: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
ae80: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
ae90: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
aea0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
aeb0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
aec0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
aed0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
aee0: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
aef0: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
af00: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
af10: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
af20: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
af30: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
af40: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
af50: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
af60: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
af70: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
af80: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
af90: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
afa0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
afb0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
afc0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
afd0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
afe0: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
aff0: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
b000: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
b010: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
b020: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
b030: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
b040: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
b050: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
b060: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b070: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
b080: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
b090: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
b0a0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
b0b0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
b0c0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
b0d0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
b0e0: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
b0f0: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
b100: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
b110: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
b120: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
b130: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
b140: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
b150: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
b160: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
b170: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
b180: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b190: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
b1a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
b1b0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
b1c0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b1d0: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
b1e0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
b1f0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
b200: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
b210: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
b220: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
b230: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
b240: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
b250: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
b260: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
b270: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
b280: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
b290: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
b2a0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
b2b0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
b2c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
b2d0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
b2e0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
b2f0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
b300: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
b310: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
b320: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
b330: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
b340: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
b350: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
b360: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
b370: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
b380: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b390: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
b3a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
b3b0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
b3c0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
b3d0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
b3e0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
b3f0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
b400: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
b410: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
b420: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
b430: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
b440: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
b450: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
b460: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
b470: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
b480: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b490: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
b4a0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
b4b0: 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  nt).  The.** sql
b4c0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
b4d0: 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
b4e0: 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69  d only be used i
b4f0: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
b500: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
b510: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
b520: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
b530: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a  lite3_open()],.*
b540: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
b550: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
b560: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a  3_open_v2()].  .
b570: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
b580: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
b590: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
b5a0: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
b5b0: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
b5c0: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67   verb - an integ
b5d0: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64  er code that ind
b5e0: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61  icates what.** a
b5f0: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
b600: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b610: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
b620: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f  igured..** The o
b630: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74  nly choice for t
b640: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51  his value is [SQ
b650: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
b660: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77  OKASIDE]..** New
b670: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c   verbs are likel
b680: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e  y to be added in
b690: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
b6a0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41   of SQLite..** A
b6b0: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
b6c0: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68  nts depend on th
b6d0: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  e verb..**.** ^C
b6e0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b6f0: 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
b700: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
b710: 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
b720: 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
b730: 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
b740: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
b750: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
b760: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
b770: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b780: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
b790: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
b7a0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
b7b0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
b7c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
b7d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
b7e0: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
b7f0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
b800: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
b810: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
b820: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
b830: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
b840: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
b850: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
b860: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
b870: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
b880: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
b890: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
b8a0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
b8b0: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
b8c0: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
b8d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
b8e0: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
b8f0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
b900: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
b910: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
b920: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
b930: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
b940: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
b950: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
b960: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
b970: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
b980: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
b990: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
b9a0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
b9b0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
b9c0: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
b9d0: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
b9e0: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
b9f0: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
ba00: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
ba10: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
ba20: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
ba30: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
ba40: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
ba50: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
ba60: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
ba70: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
ba80: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
ba90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
baa0: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
bab0: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
bac0: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
bad0: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
bae0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
baf0: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
bb00: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
bb10: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
bb20: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
bb30: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
bb40: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
bb50: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
bb60: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
bb70: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
bb80: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
bb90: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
bba0: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
bbb0: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
bbc0: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
bbd0: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
bbe0: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
bbf0: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
bc00: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
bc10: 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72   xMalloc and xFr
bc20: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
bc30: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
bc40: 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
bc50: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
bc60: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
bc70: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
bc80: 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  he xRealloc meth
bc90: 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  od must work lik
bca0: 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d  e realloc() from
bcb0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
bcc0: 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20  library.** with 
bcd0: 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68  the exception th
bce0: 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64  at if the second
bcf0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65   argument to xRe
bd00: 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a  alloc is zero,.*
bd10: 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20  * xRealloc must 
bd20: 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20  be a no-op - it 
bd30: 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d  must not perform
bd40: 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   any allocation 
bd50: 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69  or.** deallocati
bd60: 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75 61  on.  ^SQLite gua
bd70: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
bd80: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
bd90: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
bda0: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
bdb0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
bdc0: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
bdd0: 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73  oundup..** And s
bde0: 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65  o in cases where
bdf0: 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73   xRoundup always
be00: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
be10: 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78  ive number,.** x
be20: 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66  Realloc can perf
be30: 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74  orm exactly as t
be40: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
be50: 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  ary realloc() an
be60: 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e  d.** still be in
be70: 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68   compliance with
be80: 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74   this specificat
be90: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ion..**.** xSize
bea0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
beb0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
bec0: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
bed0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
bee0: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
bef0: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
bf00: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
bf10: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
bf20: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
bf30: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
bf40: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
bf50: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
bf60: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
bf70: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
bf80: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
bf90: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
bfa0: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
bfb0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bfc0: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
bfd0: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
bfe0: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
bff0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
c000: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
c010: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
c020: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
c030: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
c040: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
c050: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
c060: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
c070: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
c080: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
c090: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c0a0: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
c0b0: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
c0c0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
c0d0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
c0e0: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
c0f0: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
c100: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
c110: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
c120: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
c130: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
c140: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
c150: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
c160: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
c170: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
c180: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
c190: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
c1a0: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
c1b0: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
c1c0: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
c1d0: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
c1e0: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
c1f0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
c200: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
c210: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
c220: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
c230: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
c240: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
c250: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
c260: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
c270: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
c280: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
c290: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
c2a0: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
c2b0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
c2c0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
c2d0: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
c2e0: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
c2f0: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
c300: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
c310: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
c320: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
c330: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
c340: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
c350: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
c360: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
c370: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
c380: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
c390: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
c3a0: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
c3b0: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
c3c0: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
c3d0: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
c3e0: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
c3f0: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
c400: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
c410: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
c420: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
c430: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
c440: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
c450: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
c460: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
c470: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
c480: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
c490: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
c4a0: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
c4b0: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
c4c0: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
c4d0: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
c4e0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
c4f0: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
c500: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
c510: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
c520: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
c530: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
c540: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
c550: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
c560: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
c570: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
c580: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
c590: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
c5a0: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
c5b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
c5c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
c5d0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
c5e0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
c5f0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
c600: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
c610: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
c620: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
c630: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
c640: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
c650: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
c660: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
c670: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
c680: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
c690: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
c6a0: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
c6b0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
c6c0: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
c6d0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
c6e0: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
c6f0: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
c700: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
c710: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
c720: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
c730: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
c740: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
c750: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
c760: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
c770: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
c780: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
c790: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
c7a0: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
c7b0: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
c7c0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
c7d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
c7e0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
c7f0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
c800: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
c810: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
c820: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
c830: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c840: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
c850: 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
c860: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
c870: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
c880: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
c890: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
c8a0: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
c8b0: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
c8c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
c8d0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
c8e0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
c8f0: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
c900: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
c910: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
c920: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
c930: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
c940: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
c950: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
c960: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
c970: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
c980: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
c990: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
c9a0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
c9b0: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
c9c0: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
c9d0: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
c9e0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
c9f0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
ca00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
ca10: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
ca20: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
ca30: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
ca40: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
ca50: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
ca60: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
ca70: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
ca80: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
ca90: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
caa0: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
cab0: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
cac0: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
cad0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
cae0: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
caf0: 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
cb00: 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
cb10: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
cb20: 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
cb30: 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
cb40: 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
cb50: 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
cb60: 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
cb70: 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
cb80: 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
cb90: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
cba0: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
cbb0: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
cbc0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
cbd0: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
cbe0: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
cbf0: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
cc00: 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
cc10: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
cc20: 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
cc30: 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
cc40: 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
cc50: 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
cc60: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
cc70: 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
cc80: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
cc90: 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
cca0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
ccb0: 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
ccc0: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
ccd0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
cce0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
ccf0: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
cd00: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
cd10: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
cd20: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
cd30: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
cd40: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
cd50: 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
cd60: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
cd70: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
cd80: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
cd90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
cda0: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
cdb0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
cdc0: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
cdd0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
cde0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
cdf0: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
ce00: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
ce10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
ce20: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
ce30: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
ce40: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
ce50: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
ce60: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
ce70: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
ce80: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
ce90: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
cea0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
ceb0: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
cec0: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
ced0: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
cee0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
cef0: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
cf00: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
cf10: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
cf20: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
cf30: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
cf40: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
cf50: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
cf60: 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
cf70: 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
cf80: 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
cf90: 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
cfa0: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
cfb0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
cfc0: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
cfd0: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
cfe0: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
cff0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d000: 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
d010: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
d020: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d030: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
d040: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
d050: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
d060: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
d070: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
d080: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
d090: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
d0a0: 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
d0b0: 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
d0c0: 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
d0d0: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
d0e0: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
d0f0: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
d100: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
d110: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d120: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
d130: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
d140: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
d150: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
d160: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
d170: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
d180: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
d190: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
d1a0: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
d1b0: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
d1c0: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
d1d0: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
d1e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
d1f0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
d200: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
d210: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
d220: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
d230: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
d240: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d250: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
d260: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
d270: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
d280: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
d290: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
d2a0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
d2b0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
d2c0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
d2d0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
d2e0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
d2f0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
d300: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
d310: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
d320: 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
d330: 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
d340: 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
d350: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
d360: 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
d370: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
d380: 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
d390: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
d3a0: 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
d3b0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
d3c0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d3d0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d3e0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
d3f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d400: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d410: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d420: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d430: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d440: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
d450: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
d460: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
d470: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
d480: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
d490: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
d4a0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
d4b0: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
d4c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
d4d0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
d4e0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
d4f0: 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
d500: 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
d510: 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
d520: 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
d530: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d540: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
d550: 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
d560: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
d570: 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
d580: 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
d590: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d5a0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
d5b0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
d5c0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d5d0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d5e0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d5f0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
d600: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
d610: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d620: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
d630: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
d640: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
d650: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
d660: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
d670: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
d680: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
d690: 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
d6a0: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
d6b0: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
d6c0: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
d6d0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
d6e0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
d6f0: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
d700: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
d710: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
d720: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
d730: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
d740: 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
d750: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d760: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
d770: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
d780: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
d790: 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
d7a0: 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
d7b0: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
d7c0: 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
d7d0: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
d7e0: 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
d7f0: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
d800: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
d810: 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
d820: 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
d830: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
d840: 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
d850: 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
d860: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
d870: 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
d880: 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
d890: 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
d8a0: 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
d8b0: 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
d8c0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
d8d0: 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
d8e0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
d8f0: 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
d900: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
d910: 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
d920: 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
d930: 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
d940: 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
d950: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
d960: 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
d970: 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
d980: 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
d990: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
d9a0: 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
d9b0: 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
d9c0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
d9d0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
d9e0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
d9f0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
da00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
da10: 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
da20: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
da30: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
da40: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
da50: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
da60: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
da70: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
da80: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
da90: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
daa0: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
dab0: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
dac0: 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
dad0: 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61  he scrach alloca
dae0: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
daf0: 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
db00: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
db10: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
db20: 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
db30: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
db40: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
db50: 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
db60: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
db70: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
db80: 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72  f 16. The sz par
db90: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
dba0: 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20   a few bytes.** 
dbb0: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
dbc0: 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73  actual scratch s
dbd0: 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75  pace required du
dbe0: 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f 76  e to internal ov
dbf0: 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20 66  erhead..** The f
dc00: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
dc10: 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
dc20: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
dc30: 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
dc40: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
dc50: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
dc60: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
dc70: 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
dc80: 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75  n one scratch bu
dc90: 66 66 65 72 20 70 65 72 20 74 68 72 65 61 64 2e  ffer per thread.
dca0: 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64    So.** N should
dcb0: 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65   be set to the e
dcc0: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
dcd0: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
dce0: 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
dcf0: 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71 75 69 72  .** never requir
dd00: 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
dd10: 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
dd20: 74 68 61 6e 20 36 20 74 69 6d 65 73 20 74 68 65  than 6 times the
dd30: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67   database.** pag
dd40: 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
dd50: 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
dd60: 64 64 69 74 69 6f 6e 61 6c 20 73 63 72 61 74 63  dditional scratc
dd70: 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
dd80: 0a 2a 2a 20 77 68 61 74 20 69 73 20 70 72 6f 76  .** what is prov
dd90: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
dda0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ddb0: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
ddc0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
ddd0: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
dde0: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
ddf0: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
de00: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
de10: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
de20: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
de30: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
de40: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
de50: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
de60: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
de70: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
de80: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
de90: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
dea0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
deb0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
dec0: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
ded0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
dee0: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
def0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
df00: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
df10: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
df20: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
df30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
df40: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
df50: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
df60: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
df70: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
df80: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
df90: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
dfa0: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
dfb0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
dfc0: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
dfd0: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
dfe0: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
dff0: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
e000: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
e010: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
e020: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
e030: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
e040: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
e050: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
e060: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
e070: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
e080: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
e090: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
e0a0: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
e0b0: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
e0c0: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
e0d0: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
e0e0: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
e0f0: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
e100: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
e110: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
e120: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
e130: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
e140: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
e150: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
e160: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
e170: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
e180: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
e190: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
e1a0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e1b0: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
e1c0: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
e1d0: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
e1e0: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
e1f0: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
e200: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
e210: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
e220: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
e230: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
e240: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
e250: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
e260: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
e270: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
e280: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
e290: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
e2a0: 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  * ^The implement
e2b0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20  ation might use 
e2c0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
e2d0: 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20  he N buffers to 
e2e0: 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20  hold .** memory 
e2f0: 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72  accounting infor
e300: 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69 6e  mation. The poin
e310: 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
e320: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
e330: 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
e340: 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
e350: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
e360: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
e370: 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
e380: 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
e390: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e3a0: 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
e3b0: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
e3c0: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
e3d0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
e3e0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
e3f0: 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
e400: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
e410: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
e420: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
e430: 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
e440: 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
e450: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
e460: 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
e470: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
e480: 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
e490: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
e4a0: 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
e4b0: 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
e4c0: 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
e4d0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
e4e0: 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
e4f0: 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
e500: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
e510: 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
e520: 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
e530: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
e540: 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
e550: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
e560: 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
e570: 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
e580: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
e590: 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
e5a0: 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
e5b0: 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
e5c0: 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
e5d0: 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
e5e0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
e5f0: 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
e600: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
e610: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
e620: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
e630: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
e640: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
e650: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
e660: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
e670: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
e680: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
e690: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
e6a0: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
e6b0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
e6c0: 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
e6d0: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
e6e0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
e6f0: 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
e700: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
e710: 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
e720: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
e730: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
e740: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
e750: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e760: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
e770: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
e780: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
e790: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
e7a0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
e7b0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
e7c0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
e7d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
e7e0: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
e7f0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
e800: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
e810: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
e820: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
e830: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
e840: 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
e850: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
e860: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
e870: 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
e880: 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
e890: 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20  e.** content of 
e8a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
e8b0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
e8c0: 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
e8d0: 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
e8e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
e8f0: 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
e900: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
e910: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
e920: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
e930: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e940: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
e950: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
e960: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
e970: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
e980: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
e990: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
e9a0: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
e9b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e9c0: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
e9d0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
e9e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e9f0: 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
ea00: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
ea10: 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ].</dd>.**.** <d
ea20: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ea30: 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
ea40: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
ea50: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
ea60: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
ea70: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
ea80: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
ea90: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
eaa0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
eab0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
eac0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
ead0: 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
eae0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
eaf0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
eb00: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
eb10: 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
eb20: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
eb30: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
eb40: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
eb50: 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
eb60: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
eb70: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
eb80: 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
eb90: 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
eba0: 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
ebb0: 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
ebc0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
ebd0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
ebe0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
ebf0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
ec00: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
ec10: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
ec20: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ec30: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
ec40: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
ec50: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
ec60: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
ec70: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
ec80: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
ec90: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
eca0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
ecb0: 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
ecc0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
ecd0: 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
ece0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
ecf0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ed00: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
ed10: 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
ed20: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
ed30: 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
ed40: 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
ed50: 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
ed60: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
ed70: 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
ed80: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
ed90: 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
eda0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
edb0: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
edc0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
edd0: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
ede0: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
edf0: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
ee00: 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
ee10: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
ee20: 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
ee30: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
ee40: 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
ee50: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
ee60: 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
ee70: 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
ee80: 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
ee90: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
eea0: 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
eeb0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
eec0: 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
eed0: 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
eee0: 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
eef0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
ef00: 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
ef10: 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
ef20: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
ef30: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64  CONFIG_PCACHE</d
ef40: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
ef50: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
ef60: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
ef70: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
ef80: 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
ef90: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
efa0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  hods] object.  T
efb0: 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69  his object speci
efc0: 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  fies the interfa
efd0: 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f  ce.** to a custo
efe0: 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  m page cache imp
eff0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20  lementation.)^  
f000: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
f010: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
f020: 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 69  bject and uses i
f030: 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  t for page cache
f040: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f050: 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ons.</dd>.**.** 
f060: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f070: 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e  G_GETPCACHE</dt>
f080: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f090: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
f0a0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
f0b0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
f0c0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
f0d0: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
f0e0: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
f0f0: 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
f100: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
f110: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
f120: 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
f130: 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
f140: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f150: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
f160: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
f170: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
f180: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
f190: 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70  o arguments: a p
f1a0: 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66  ointer to a.** f
f1b0: 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63  unction with a c
f1c0: 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66  all signature of
f1d0: 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69   void(*)(void*,i
f1e0: 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  nt,const char*),
f1f0: 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74   .** and a point
f200: 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20  er to void. ^If 
f210: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
f220: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
f230: 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b  , it is.** invok
f240: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
f250: 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73  og()] to process
f260: 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76   each logging ev
f270: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
f280: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
f290: 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b  r is NULL, the [
f2a0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69  sqlite3_log()] i
f2b0: 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73  nterface becomes
f2c0: 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68   a no-op..** ^Th
f2d0: 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74  e void pointer t
f2e0: 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e  hat is the secon
f2f0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51  d argument to SQ
f300: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
f310: 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72  is.** passed thr
f320: 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73  ough as the firs
f330: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
f340: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
f350: 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
f360: 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76   function whenev
f370: 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  er that function
f380: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54   is invoked.  ^T
f390: 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
f3a0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f  ter to.** the lo
f3b0: 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73  gger function is
f3c0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
f3d0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
f3e0: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
f3f0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
f400: 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20  log()] call and 
f410: 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62  is intended to b
f420: 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  e a [result code
f430: 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65  ] or an.** [exte
f440: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
f450: 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  ].  ^The third p
f460: 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20  arameter passed 
f470: 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73  to the logger is
f480: 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20  .** log message 
f490: 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67  after formatting
f4a0: 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e   via [sqlite3_sn
f4b0: 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68  printf()]..** Th
f4c0: 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67  e SQLite logging
f4d0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
f4e0: 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65  t reentrant; the
f4f0: 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
f500: 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20  .** supplied by 
f510: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
f520: 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20  must not invoke 
f530: 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
f540: 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75  face..** In a mu
f550: 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70  lti-threaded app
f560: 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70  lication, the ap
f570: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
f580: 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
f590: 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72  tion must be thr
f5a0: 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a  eadsafe. </dd>.*
f5b0: 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
f5c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
f5d0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
f5e0: 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
f5f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f600: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
f610: 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
f620: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f630: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
f640: 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
f650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f660: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
f670: 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
f680: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
f690: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f6a0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
f6b0: 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
f6c0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
f6d0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
f6e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
f6f0: 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
f700: 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
f710: 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
f720: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
f730: 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
f740: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
f750: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
f760: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
f770: 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
f780: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
f790: 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
f7a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f7b0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
f7c0: 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
f7d0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
f7e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
f7f0: 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
f800: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
f810: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
f820: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
f830: 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
f840: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
f850: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
f860: 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
f870: 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
f880: 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
f890: 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
f8a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f8b0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
f8c0: 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
f8d0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
f8e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
f8f0: 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73  E       14  /* s
f900: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
f910: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
f920: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f930: 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
f940: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
f950: 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
f960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f970: 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
f980: 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
f990: 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  void* */../*.** 
f9a0: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
f9b0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
f9c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
f9d0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
f9e0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
f9f0: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
fa00: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
fa10: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
fa20: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
fa30: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
fa40: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
fa50: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
fa60: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
fa70: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
fa80: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
fa90: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
faa0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
fab0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
fac0: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
fad0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
fae0: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
faf0: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
fb00: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
fb10: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
fb20: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
fb30: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
fb40: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
fb50: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
fb60: 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
fb70: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
fb80: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
fb90: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
fba0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
fbb0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
fbc0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
fbd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
fbe0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
fbf0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
fc00: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
fc10: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
fc20: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
fc30: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
fc40: 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
fc50: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
fc60: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
fc70: 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
fc80: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
fc90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
fca0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
fcb0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
fcc0: 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
fcd0: 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
fce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
fcf0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
fd00: 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
fd10: 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75   to an memory bu
fd20: 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
fd30: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
fd40: 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
fd50: 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
fd60: 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
fd70: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
fd80: 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
fd90: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
fda0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
fdb0: 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
fdc0: 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
fdd0: 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
fde0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
fdf0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fe00: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
fe10: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
fe20: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
fe30: 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
fe40: 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
fe50: 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
fe60: 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
fe70: 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
fe80: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
fe90: 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
fea0: 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
feb0: 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
fec0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
fed0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
fee0: 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
fef0: 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
ff00: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
ff10: 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
ff20: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
ff30: 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
ff40: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
ff50: 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
ff60: 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
ff70: 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
ff80: 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
ff90: 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20  next smaller.** 
ffa0: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
ffb0: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
ffc0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
ffd0: 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  DE]</dd>.**.** <
ffe0: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
fff0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
10000 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30  LOOKASIDE    100
10010 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
10020 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  int */.../*.** C
10030 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
10040 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
10050 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
10060 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10070 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
10080 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
10090 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
100a0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
100b0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
100c0 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
100d0 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
100e0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
100f0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
10100 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
10110 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
10120 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
10130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
10140 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
10150 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
10160 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
10170 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
10180 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
10190 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
101a0 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
101b0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
101c0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
101d0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
101e0 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
101f0 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
10200 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
10210 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
10220 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
10230 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
10240 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
10250 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
10260 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
10270 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
10280 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
10290 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
102a0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
102b0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
102c0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
102d0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
102e0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
102f0 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
10300 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
10310 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
10320 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
10330 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
10340 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
10350 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
10360 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
10370 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
10380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
10390 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
103a0 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f  rgument.  ^If no
103b0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
103c0 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
103d0 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
103e0 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
103f0 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
10400 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
10410 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
10420 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
10430 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20  a trigger, then 
10440 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
10450 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
10460 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
10470 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
10480 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
10490 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67  igger is running
104a0 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
104b0 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
104c0 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
104d0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
104e0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65   routine.** reve
104f0 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
10500 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
10510 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
10520 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  r fired.)^.**.**
10530 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
10540 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
10550 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
10560 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
10570 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
10580 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
10590 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
105a0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
105b0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
105c0 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
105d0 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
105e0 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
105f0 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
10600 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
10610 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
10620 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
10630 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
10640 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
10650 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
10660 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
10670 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
10680 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
10690 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
106a0 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
106b0 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
106c0 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
106d0 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
106e0 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
106f0 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
10700 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
10710 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
10720 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
10730 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
10740 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
10750 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
10760 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
10770 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
10780 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
10790 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
107a0 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
107b0 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
107c0 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
107d0 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
107e0 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
107f0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
10800 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
10810 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
10820 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
10830 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
10840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
10850 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
10860 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
10870 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
10880 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
10890 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
108a0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
108b0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
108c0 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
108d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
108e0 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
108f0 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
10900 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
10910 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
10920 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
10930 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
10940 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
10950 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
10960 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
10970 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
10980 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
10990 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
109a0 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
109b0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
109c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
109d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
109e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
109f0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
10a00 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
10a10 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
10a20 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
10a30 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
10a40 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
10a50 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
10a60 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
10a70 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
10a80 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
10a90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
10aa0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
10ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
10ac0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
10ad0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
10ae0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
10af0 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
10b00 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
10b10 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
10b20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
10b30 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
10b40 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
10b50 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
10b60 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
10b70 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
10b80 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
10b90 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
10ba0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
10bb0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
10bc0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
10bd0 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
10be0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
10bf0 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
10c00 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
10c10 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
10c20 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
10c30 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
10c40 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
10c50 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
10c60 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
10c70 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
10c80 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
10c90 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
10ca0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
10cb0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
10cc0 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
10cd0 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
10ce0 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
10cf0 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
10d00 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
10d10 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
10d20 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
10d30 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
10d40 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
10d50 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
10d60 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
10d70 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
10d80 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
10d90 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
10da0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
10db0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
10dc0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
10dd0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
10de0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
10df0 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
10e00 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
10e10 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
10e20 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
10e30 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
10e40 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
10e50 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
10e60 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
10e70 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
10e80 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
10e90 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
10ea0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
10eb0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
10ec0 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
10ed0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
10ee0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
10ef0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
10f00 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
10f10 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
10f20 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
10f30 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
10f40 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
10f50 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
10f60 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
10f70 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
10f80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
10f90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
10fa0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
10fb0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
10fc0 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
10fd0 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
10fe0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
10ff0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
11000 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11010 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
11020 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
11030 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
11040 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
11050 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
11060 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
11070 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
11080 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
11090 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
110a0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
110b0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
110c0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
110d0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
110e0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
110f0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
11100 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
11110 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
11120 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
11130 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
11140 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
11150 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
11160 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
11170 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
11180 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
11190 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
111a0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
111b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
111c0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
111d0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
111e0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
111f0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
11200 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
11210 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
11220 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
11230 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
11240 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
11250 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
11260 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
11270 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
11280 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
11290 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
112a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
112b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
112c0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
112d0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
112e0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
112f0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
11300 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
11310 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
11320 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
11330 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
11340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11350 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
11360 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
11370 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
11380 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
11390 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
113a0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
113b0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
113c0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
113d0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
113e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
113f0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
11400 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
11410 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
11420 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
11430 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
11440 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
11450 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
11460 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
11470 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
11480 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11490 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
114a0 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
114b0 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
114c0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
114d0 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
114e0 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
114f0 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
11500 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
11510 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
11520 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
11530 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
11540 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
11550 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
11560 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
11570 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
11580 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
11590 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
115a0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
115b0 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
115c0 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
115d0 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
115e0 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
115f0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
11600 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
11610 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
11620 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
11630 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
11640 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
11650 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
11660 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
11670 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
11680 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
11690 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
116a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
116b0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
116c0 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
116d0 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
116e0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
116f0 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
11700 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
11710 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
11720 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
11730 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
11740 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
11750 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
11760 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
11770 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
11780 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
11790 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
117a0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
117b0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
117c0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
117d0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
117e0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
117f0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
11800 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
11810 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11820 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
11830 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11840 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
11850 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
11860 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
11870 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
11880 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
11890 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
118a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
118b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
118c0 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
118d0 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
118e0 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
118f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
11900 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
11910 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
11920 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
11930 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
11940 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
11950 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
11960 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
11970 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
11980 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
11990 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
119a0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
119b0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
119c0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
119d0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
119e0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
119f0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
11a00 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
11a10 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
11a20 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
11a30 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
11a40 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
11a50 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
11a60 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
11a70 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
11a80 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
11a90 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
11aa0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
11ab0 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
11ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11ad0 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
11ae0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
11af0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
11b00 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
11b10 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
11b20 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
11b30 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
11b40 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
11b50 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
11b60 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11b70 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
11b80 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
11b90 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
11ba0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
11bb0 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
11bc0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
11bd0 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
11be0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
11bf0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
11c00 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
11c10 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
11c20 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
11c30 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
11c40 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
11c50 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
11c60 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
11c70 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
11c80 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
11c90 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
11ca0 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
11cb0 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
11cc0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
11cd0 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
11ce0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11cf0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
11d00 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
11d10 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
11d20 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
11d30 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
11d40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
11d50 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
11d60 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
11d70 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
11d80 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
11d90 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
11da0 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
11db0 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
11dc0 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
11dd0 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
11de0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
11df0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
11e00 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
11e10 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
11e20 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
11e30 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
11e40 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
11e50 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
11e60 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
11e70 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
11e80 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
11e90 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
11ea0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
11eb0 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
11ec0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
11ed0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
11ee0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
11ef0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
11f00 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
11f10 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
11f20 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
11f30 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
11f40 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
11f50 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
11f60 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
11f70 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
11f80 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
11f90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
11fa0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
11fb0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
11fc0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
11fd0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
11fe0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
11ff0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
12000 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
12010 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
12020 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12030 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
12040 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
12050 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
12060 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
12070 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
12080 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
12090 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
120a0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
120b0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
120c0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
120d0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
120e0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
120f0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
12100 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
12110 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
12120 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
12130 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
12140 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
12150 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
12160 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
12170 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
12180 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
12190 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
121a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
121b0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
121c0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
121d0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
121e0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
121f0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
12200 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
12210 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
12220 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
12230 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
12240 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
12250 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
12260 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
12270 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
12280 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
12290 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
122a0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
122b0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
122c0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
122d0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
122e0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
122f0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
12300 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
12310 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
12320 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
12330 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
12340 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
12350 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
12360 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
12370 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
12380 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
12390 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
123a0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
123b0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
123c0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
123d0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
123e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
123f0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
12400 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
12410 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
12420 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
12430 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
12440 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
12450 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
12460 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
12470 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
12480 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12490 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
124a0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
124b0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
124c0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
124d0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
124e0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
124f0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
12500 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
12510 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
12520 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
12530 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
12540 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
12550 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
12560 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
12570 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
12580 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
12590 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
125a0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
125b0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
125c0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
125d0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
125e0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
125f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
12600 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
12610 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
12620 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
12630 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
12640 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
12650 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
12660 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
12670 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
12680 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
12690 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
126a0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
126b0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
126c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
126d0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
126e0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
126f0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
12700 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
12710 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
12720 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
12730 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
12740 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
12750 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
12760 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
12770 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
12780 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
12790 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
127a0 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
127b0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
127c0 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
127d0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
127e0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
127f0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
12800 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
12810 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
12820 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
12830 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
12840 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
12850 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
12860 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
12870 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
12880 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
12890 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
128a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
128b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
128c0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
128d0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
128e0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
128f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
12900 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
12910 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
12920 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
12930 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
12940 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
12950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
12960 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
12970 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
12980 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
12990 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
129a0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
129b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
129c0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
129d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
129e0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
129f0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
12a00 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
12a10 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
12a20 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
12a30 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
12a40 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
12a50 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
12a60 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
12a70 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
12a80 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
12a90 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
12aa0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
12ab0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
12ac0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
12ad0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
12ae0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
12af0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
12b00 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
12b10 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
12b20 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
12b30 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
12b40 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
12b50 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
12b60 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
12b70 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
12b80 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
12b90 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
12ba0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
12bb0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
12bc0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
12bd0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
12be0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
12bf0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
12c00 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
12c10 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
12c20 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
12c30 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
12c40 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
12c50 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
12c60 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
12c70 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
12c80 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
12c90 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
12ca0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
12cb0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
12cc0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
12cd0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
12ce0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
12cf0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
12d00 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
12d10 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
12d20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
12d30 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
12d40 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
12d50 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
12d60 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
12d70 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
12d80 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
12d90 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
12da0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
12db0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
12dc0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
12dd0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
12de0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
12df0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
12e00 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
12e10 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
12e20 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
12e30 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
12e40 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
12e50 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
12e60 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
12e70 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
12e80 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
12e90 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
12ea0 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
12eb0 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
12ec0 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
12ed0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
12ee0 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
12ef0 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
12f00 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
12f10 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
12f20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
12f30 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
12f40 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
12f50 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
12f60 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
12f70 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
12f80 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
12f90 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
12fa0 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
12fb0 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
12fc0 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
12fd0 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
12fe0 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
12ff0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
13000 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
13010 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
13020 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
13030 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
13040 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
13050 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
13060 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
13070 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
13080 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
13090 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
130a0 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
130b0 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
130c0 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
130d0 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
130e0 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
130f0 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
13100 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13110 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
13120 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
13130 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
13140 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
13150 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
13160 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
13170 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
13180 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
13190 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
131a0 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
131b0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
131c0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
131d0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
131e0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
131f0 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
13200 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
13210 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
13220 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
13230 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
13240 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
13250 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
13260 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
13270 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
13280 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
13290 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
132a0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
132b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
132c0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
132d0 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
132e0 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
132f0 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
13300 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
13310 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
13320 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
13330 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
13340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13350 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
13360 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
13370 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
13380 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
13390 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
133a0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
133b0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
133c0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
133d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
133e0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
133f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
13400 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
13410 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
13420 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
13430 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
13440 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
13450 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
13460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
13470 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
13480 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
13490 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
134a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
134b0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
134c0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
134d0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
134e0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
134f0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
13500 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
13510 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
13520 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
13530 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
13540 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
13550 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
13560 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
13570 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
13580 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
13590 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
135a0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
135b0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
135c0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
135d0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
135e0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
135f0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
13600 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
13610 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
13620 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
13630 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
13640 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
13650 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
13660 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
13670 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
13680 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
13690 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
136a0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
136b0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
136c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
136d0 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
136e0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
136f0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
13700 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
13710 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
13720 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
13730 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
13740 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
13750 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
13760 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
13770 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e  cleared.)^.*/.in
13780 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
13790 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
137a0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
137b0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
137c0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
137d0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
137e0 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ies.**.** Defini
137f0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
13800 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
13810 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
13820 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
13830 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
13840 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
13850 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
13860 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
13870 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
13880 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
13890 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
138a0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
138b0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
138c0 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
138d0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
138e0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
138f0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
13900 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
13910 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
13920 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
13930 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
13940 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
13950 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
13960 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
13970 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
13980 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
13990 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
139a0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
139b0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
139c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
139d0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
139e0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
139f0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
13a00 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
13a10 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
13a20 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
13a30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
13a40 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
13a50 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
13a60 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
13a70 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
13a80 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
13a90 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
13aa0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
13ab0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
13ac0 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
13ad0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
13ae0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
13af0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
13b00 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
13b10 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
13b20 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
13b30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
13b40 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
13b50 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
13b60 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
13b70 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
13b80 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
13b90 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
13ba0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
13bb0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
13bc0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
13bd0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
13be0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
13bf0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
13c00 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
13c10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ()]..**.** As an
13c20 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
13c30 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
13c40 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
13c50 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
13c60 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
13c70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13c80 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
13c90 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
13ca0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
13cb0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
13cc0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
13cd0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
13ce0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
13cf0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
13d00 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
13d10 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
13d20 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13d30 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
13d40 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
13d50 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
13d60 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
13d70 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
13d80 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
13d90 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
13da0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
13db0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
13dc0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
13dd0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
13de0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
13df0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
13e00 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
13e10 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13e20 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
13e30 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13e40 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
13e50 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
13e60 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
13e70 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
13e80 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
13e90 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
13ea0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13eb0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
13ec0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
13ed0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
13ee0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13ef0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
13f00 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
13f10 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
13f20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
13f30 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
13f40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
13f50 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
13f60 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
13f70 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
13f80 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
13f90 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
13fa0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
13fb0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
13fc0 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
13fd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
13fe0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
13ff0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
14000 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
14010 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
14020 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
14030 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
14040 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
14050 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
14060 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
14070 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73  table(),.** it s
14080 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72  hould pass the r
14090 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
140a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
140b0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
140c0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
140d0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
140e0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
140f0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
14100 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
14110 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
14120 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
14130 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14140 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
14150 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14160 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
14170 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
14180 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
14190 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
141a0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
141b0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
141c0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
141d0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
141e0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
141f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
14200 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
14210 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
14220 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
14230 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
14240 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
14250 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
14260 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
14270 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
14280 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
14290 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
142a0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
142b0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
142c0 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
142d0 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
142e0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
142f0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
14300 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
14310 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
14320 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
14330 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
14340 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
14350 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
14360 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
14370 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
14380 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
14390 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a  3_errmsg()].)^.*
143a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
143b0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
143c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
143d0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
143e0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
143f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
14400 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
14410 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
14420 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
14430 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
14440 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
14450 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
14460 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
14470 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
14480 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
14490 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
144a0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
144b0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
144c0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
144d0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
144e0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
144f0 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
14500 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
14510 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14520 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
14530 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14540 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
14550 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
14560 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
14570 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
14580 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
14590 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
145a0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
145b0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
145c0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
145d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
145e0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
145f0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
14600 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
14610 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
14620 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
14630 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
14640 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14650 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
14660 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
14670 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
14680 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
14690 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
146a0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
146b0 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
146c0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
146d0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
146e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
146f0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
14700 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
14710 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
14720 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
14730 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69  .**.** ^(In sqli
14740 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
14750 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
14760 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
14770 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
14780 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
14790 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
147a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
147b0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
147c0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
147d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
147e0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
147f0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
14800 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
14810 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
14820 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
14830 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
14840 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
14850 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
14860 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
14870 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
14880 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
14890 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
148a0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
148b0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
148c0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
148d0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
148e0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
148f0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
14900 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
14910 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
14920 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
14930 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
14940 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
14950 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
14960 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
14970 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
14980 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
14990 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
149a0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
149b0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
149c0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
149d0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
149e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
149f0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
14a00 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
14a10 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
14a20 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
14a30 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
14a40 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
14a50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
14a60 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
14a70 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
14a80 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
14a90 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
14aa0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
14ab0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
14ac0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
14ad0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
14ae0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
14af0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
14b00 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
14b10 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
14b20 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
14b30 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
14b40 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
14b50 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
14b60 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
14b70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
14b80 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
14b90 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
14ba0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
14bb0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
14bc0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
14bd0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
14be0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
14bf0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
14c00 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
14c10 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
14c20 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
14c30 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
14c40 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
14c50 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
14c60 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
14c70 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
14c80 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
14c90 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
14ca0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
14cb0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
14cc0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
14cd0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
14ce0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
14cf0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
14d00 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
14d10 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
14d20 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
14d30 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
14d40 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
14d50 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
14d60 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
14d70 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
14d80 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
14d90 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
14da0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
14db0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
14dc0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
14dd0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
14de0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
14df0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
14e00 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
14e10 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14e20 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
14e30 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
14e40 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
14e50 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
14e60 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14e70 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
14e80 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
14e90 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
14ea0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
14eb0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
14ec0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
14ed0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
14ee0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
14ef0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
14f00 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
14f10 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
14f20 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
14f30 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
14f40 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
14f50 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
14f60 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
14f70 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
14f80 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
14f90 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14fa0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
14fb0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
14fc0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
14fd0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
14fe0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14ff0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
15000 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
15010 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
15020 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
15030 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
15040 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
15050 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
15060 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15070 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
15080 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
15090 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
150a0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
150b0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
150c0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
150d0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
150e0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
150f0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
15100 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
15110 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
15120 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
15130 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
15140 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
15150 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
15160 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
15170 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
15180 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
15190 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
151a0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
151b0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
151c0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
151d0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
151e0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
151f0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
15200 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
15210 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
15220 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
15230 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
15240 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
15250 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
15260 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
15270 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
15280 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
15290 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
152a0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
152b0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
152c0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
152d0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
152e0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
152f0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
15300 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
15310 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15320 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15330 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
15340 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
15350 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
15360 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
15370 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
15380 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
15390 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
153a0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
153b0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
153c0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
153d0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
153e0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
153f0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
15400 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
15410 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
15420 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
15430 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
15440 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
15450 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
15460 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
15470 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
15480 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
15490 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
154a0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
154b0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
154c0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
154d0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
154e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
154f0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
15500 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
15510 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
15520 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
15530 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
15540 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
15550 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
15560 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
15570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15580 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
15590 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
155a0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
155b0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
155c0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
155d0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
155e0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
155f0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
15600 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
15610 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
15620 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
15630 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
15640 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15650 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
15660 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
15670 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
15680 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
15690 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
156a0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
156b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
156c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
156d0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
156e0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
156f0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
15700 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
15710 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
15720 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
15730 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
15740 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
15750 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
15760 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15770 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
15780 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
15790 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
157a0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
157b0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
157c0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
157d0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
157e0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
157f0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
15800 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
15810 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
15820 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
15830 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
15840 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
15850 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
15860 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
15870 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
15880 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
15890 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
158a0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
158b0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
158c0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
158d0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
158e0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
158f0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
15900 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
15910 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
15920 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
15930 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
15940 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
15950 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
15960 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
15970 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
15980 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
15990 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
159a0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
159b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
159c0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
159d0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
159e0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
159f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
15a00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
15a10 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
15a20 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
15a30 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
15a40 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
15a50 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
15a60 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
15a70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
15a80 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
15a90 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
15aa0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
15ab0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
15ac0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15ad0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
15ae0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
15af0 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
15b00 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
15b10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
15b20 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
15b30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
15b40 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
15b50 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
15b60 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
15b70 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
15b80 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
15b90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
15ba0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
15bb0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
15bc0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15bd0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
15be0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
15bf0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
15c00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
15c10 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
15c20 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
15c30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
15c40 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
15c50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15c60 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
15c70 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
15c80 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
15c90 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
15ca0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
15cb0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
15cc0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
15cd0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
15ce0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
15cf0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
15d00 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
15d10 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
15d20 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
15d30 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
15d40 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
15d50 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
15d60 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
15d70 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
15d80 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
15d90 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
15da0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
15db0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
15dc0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
15dd0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15de0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
15df0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
15e00 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
15e10 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
15e20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
15e30 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
15e40 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
15e50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
15e60 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
15e70 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
15e80 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
15e90 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ary..**.** In SQ
15ea0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
15eb0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
15ec0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
15ed0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
15ee0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
15ef0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
15f00 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
15f10 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
15f20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15f30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
15f40 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
15f50 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
15f60 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
15f70 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
15f80 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
15f90 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
15fa0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
15fb0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
15fc0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
15fd0 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
15fe0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
15ff0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
16000 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
16010 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
16020 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
16030 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
16040 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
16050 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
16060 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
16070 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
16080 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
16090 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
160a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
160b0 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
160c0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
160d0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
160e0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
160f0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
16100 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
16110 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
16120 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
16130 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
16140 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
16150 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
16160 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
16170 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
16180 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
16190 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
161a0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
161b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
161c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
161d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
161e0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
161f0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
16200 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
16210 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
16220 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
16230 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
16240 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
16250 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
16260 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
16270 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
16280 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
16290 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
162a0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
162b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
162c0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
162d0 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
162e0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
162f0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
16300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16310 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
16320 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
16330 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
16340 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
16350 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
16360 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
16370 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
16380 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16390 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
163a0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
163b0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
163c0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
163d0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
163e0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
163f0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
16400 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
16410 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
16420 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
16430 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16440 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
16450 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
16460 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
16470 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
16480 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
16490 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
164a0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
164b0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
164c0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
164d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
164e0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
164f0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
16500 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
16510 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
16520 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
16530 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16540 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
16550 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16560 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
16570 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
16580 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
16590 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
165a0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
165b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
165c0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
165d0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
165e0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
165f0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
16600 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
16610 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16620 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
16630 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
16640 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
16650 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
16660 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
16670 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
16680 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
16690 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
166a0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
166b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
166c0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
166d0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
166e0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
166f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
16700 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
16710 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
16720 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
16730 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
16740 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
16750 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
16760 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
16770 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
16780 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
16790 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
167a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
167b0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
167c0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
167d0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
167e0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
167f0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
16800 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
16810 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
16820 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
16830 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
16840 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
16850 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
16860 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
16870 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
16880 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
16890 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
168a0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
168b0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
168c0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
168d0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
168e0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
168f0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
16900 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
16910 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
16920 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
16930 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
16940 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
16950 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
16960 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
16970 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
16980 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
16990 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
169a0 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
169b0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
169c0 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
169d0 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
169e0 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
169f0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
16a00 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
16a10 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
16a20 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
16a30 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
16a40 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
16a50 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
16a60 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
16a70 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
16a80 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
16a90 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
16aa0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
16ab0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
16ac0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
16ad0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
16ae0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
16af0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
16b00 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
16b10 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
16b20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
16b30 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
16b40 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
16b50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
16b60 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
16b70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16b80 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
16b90 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
16ba0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
16bb0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
16bc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
16bd0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
16be0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
16bf0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
16c00 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
16c10 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
16c20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
16c30 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
16c40 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
16c50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
16c60 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
16c70 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
16c80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
16c90 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
16ca0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
16cb0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
16cc0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
16cd0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
16ce0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
16cf0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
16d00 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
16d10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
16d20 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
16d30 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
16d40 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
16d50 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
16d60 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
16d70 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
16d80 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
16d90 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
16da0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
16db0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
16dc0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
16dd0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
16de0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
16df0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
16e00 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
16e10 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
16e20 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
16e30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
16e40 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
16e50 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
16e60 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
16e70 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
16e80 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
16e90 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
16ea0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
16eb0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
16ec0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
16ed0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
16ee0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
16ef0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
16f00 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
16f10 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
16f20 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
16f30 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
16f40 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
16f50 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
16f60 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
16f70 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
16f80 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
16f90 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
16fa0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
16fb0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
16fc0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
16fd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16fe0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
16ff0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
17000 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
17010 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
17020 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
17030 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
17040 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
17050 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
17060 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
17070 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17080 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17090 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
170a0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
170b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
170c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
170d0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
170e0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
170f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
17100 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
17110 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
17120 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
17130 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
17140 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
17150 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
17160 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17170 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
17180 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
17190 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
171a0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
171b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
171c0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
171d0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
171e0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
171f0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
17200 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
17210 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
17220 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
17230 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
17240 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17250 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
17260 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
17270 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
17280 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
17290 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
172a0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
172b0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
172c0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
172d0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
172e0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
172f0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
17300 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
17310 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
17320 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
17330 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
17340 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
17350 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
17360 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
17370 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
17380 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
17390 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
173a0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
173b0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
173c0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
173d0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
173e0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
173f0 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
17400 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
17410 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
17420 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
17430 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
17440 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
17450 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
17460 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
17470 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
17480 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
17490 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
174a0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
174b0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
174c0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
174d0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
174e0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
174f0 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
17500 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
17510 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
17520 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
17530 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
17540 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
17550 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
17560 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
17570 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
17580 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
17590 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
175a0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
175b0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
175c0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
175d0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
175e0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
175f0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
17600 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
17610 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
17620 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
17630 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
17640 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
17650 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
17660 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
17670 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
17680 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
17690 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
176a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
176b0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
176c0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
176d0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
176e0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
176f0 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
17700 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
17710 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
17720 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
17730 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
17740 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
17750 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
17760 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
17770 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
17780 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
17790 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
177a0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
177b0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
177c0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
177d0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
177e0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
177f0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
17800 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
17810 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
17820 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17830 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
17840 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
17850 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17860 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
17870 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
17880 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
17890 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
178a0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
178b0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
178c0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
178d0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
178e0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
178f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17900 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
17910 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
17920 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
17930 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17940 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
17950 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
17960 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
17970 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
17980 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17990 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
179a0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
179b0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
179c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
179d0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
179e0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
179f0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
17a00 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
17a10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17a20 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
17a30 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
17a40 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
17a50 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
17a60 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
17a70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
17a80 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
17a90 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
17aa0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
17ab0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
17ac0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
17ad0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
17ae0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
17af0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
17b00 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
17b10 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
17b20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
17b30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17b40 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
17b50 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
17b60 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
17b70 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
17b80 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
17b90 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
17ba0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
17bb0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
17bc0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
17bd0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
17be0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
17bf0 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
17c00 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
17c10 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
17c20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17c30 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
17c40 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
17c50 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
17c60 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
17c70 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17c80 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
17c90 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
17ca0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
17cb0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
17cc0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
17cd0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
17ce0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
17cf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
17d00 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
17d10 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
17d20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17d30 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
17d40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
17d50 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
17d60 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
17d70 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
17d80 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
17d90 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
17da0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
17db0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
17dc0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
17dd0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
17de0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
17df0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17e00 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
17e10 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
17e20 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
17e30 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
17e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17e50 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
17e60 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
17e70 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
17e80 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
17e90 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
17ea0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
17eb0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
17ec0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
17ed0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
17ee0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
17ef0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
17f00 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
17f10 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17f20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
17f30 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
17f40 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
17f50 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
17f60 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
17f70 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
17f80 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
17f90 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
17fa0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
17fb0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
17fc0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
17fd0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
17fe0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
17ff0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
18000 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
18010 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
18020 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
18030 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
18040 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
18050 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
18060 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
18070 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
18080 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
18090 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
180a0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
180b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
180c0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
180d0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
180e0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
180f0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
18100 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
18110 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
18120 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
18130 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
18140 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
18150 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
18160 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
18170 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
18180 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18190 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
181a0 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
181b0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
181c0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
181d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
181e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
181f0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
18200 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
18210 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
18220 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
18230 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
18240 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
18250 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
18260 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
18270 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
18280 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
18290 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
182a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
182b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
182c0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
182d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
182e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
182f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18300 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
18310 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
18320 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
18330 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18340 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18350 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
18360 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18370 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18380 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18390 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
183a0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
183b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
183c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
183d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
183e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
183f0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
18400 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18410 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18420 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18430 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
18440 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
18450 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18460 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18470 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18480 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
18490 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
184a0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
184b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
184c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
184d0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
184e0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
184f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
18500 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18510 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18520 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
18530 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
18540 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
18550 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18570 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
18580 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
18590 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
185a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
185b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
185c0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
185d0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
185e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
185f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18610 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
18620 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
18630 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18640 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18660 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
18670 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
18680 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
18690 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
186a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
186b0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
186c0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
186d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
186e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
186f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18700 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
18710 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
18720 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18730 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18740 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18750 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
18760 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
18770 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18780 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18790 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
187a0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
187b0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
187c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
187d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
187e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
187f0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
18800 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
18810 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18820 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18830 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
18840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
18850 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18860 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18870 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18880 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
18890 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
188a0 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
188b0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
188c0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
188d0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
188e0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
188f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18900 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
18910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18920 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
18930 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
18940 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
18950 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18970 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
18980 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
18990 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
189a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
189b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
189c0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
189d0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
189e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
189f0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
18a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18a10 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
18a20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
18a30 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
18a40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18a50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18a60 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
18a70 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
18a80 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
18a90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ab0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
18ac0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
18ad0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
18ae0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18b00 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
18b10 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
18b20 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
18b30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
18b50 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
18b60 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
18b70 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
18b80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18b90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18ba0 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
18bb0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
18bc0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
18bd0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
18be0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18bf0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
18c00 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
18c10 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
18c20 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
18c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
18c40 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
18c50 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
18c60 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
18c70 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
18c80 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
18c90 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
18ca0 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
18cb0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
18cc0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
18cd0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
18ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18cf0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
18d00 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
18d10 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
18d20 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
18d30 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
18d40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
18d50 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
18d60 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
18d70 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
18d80 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
18d90 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
18da0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
18db0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
18dc0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
18dd0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
18de0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
18df0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
18e00 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
18e10 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
18e20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
18e30 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
18e40 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
18e50 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
18e60 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
18e70 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
18e80 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
18e90 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
18ea0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
18eb0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
18ec0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
18ed0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
18ee0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
18ef0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
18f00 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
18f10 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
18f20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
18f30 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
18f40 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
18f50 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
18f60 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
18f70 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
18f80 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
18f90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
18fa0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
18fb0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
18fc0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
18fd0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
18fe0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
18ff0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
19000 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
19010 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
19020 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
19030 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
19040 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
19050 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
19060 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
19070 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
19080 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f 69 64   to run..*/.void
19090 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
190a0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
190b0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
190c0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
190d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  *);.SQLITE_EXPER
190e0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
190f0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71  lite3_profile(sq
19100 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
19110 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a  *xProfile)(void*
19120 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c  ,const char*,sql
19130 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f  ite3_uint64), vo
19140 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
19150 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
19160 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
19170 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
19180 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
19190 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
191a0 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
191b0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
191c0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
191d0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
191e0 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
191f0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
19200 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
19210 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19220 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
19230 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
19240 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
19250 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
19260 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
19270 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
19280 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
19290 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
192a0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
192b0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
192c0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
192d0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
192e0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
192f0 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
19300 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
19310 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
19320 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
19330 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
19340 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
19350 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  ss handler must 
19360 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
19370 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
19380 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
19390 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
193a0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
193b0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
193c0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
193d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
193e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
193f0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
19400 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
19410 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19420 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
19430 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
19440 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
19450 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
19460 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19470 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
19480 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
19490 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
194a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
194b0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
194c0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
194d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
194e0 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
194f0 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
19500 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
19510 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
19520 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
19530 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
19540 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
19550 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
19560 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
19570 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
19580 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
19590 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
195a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
195b0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
195c0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
195d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
195e0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
195f0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
19600 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
19610 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
19620 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
19630 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
19640 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
19650 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
19660 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
19670 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
19680 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
19690 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
196a0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
196b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
196c0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
196d0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
196e0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
196f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19700 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
19710 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
19720 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
19730 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
19740 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
19750 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
19760 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
19770 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
19780 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
19790 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
197a0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
197b0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
197c0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
197d0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
197e0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
197f0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
19800 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
19810 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
19820 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
19830 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
19840 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
19850 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
19860 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
19870 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
19880 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
19890 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
198a0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
198b0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
198c0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
198d0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
198e0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
198f0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
19900 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
19910 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
19920 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
19930 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
19940 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
19950 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
19960 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
19970 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
19980 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
19990 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
199a0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
199b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
199c0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
199d0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
199e0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
199f0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
19a00 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
19a10 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
19a20 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
19a30 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
19a40 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
19a50 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
19a60 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
19a70 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
19a80 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
19a90 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
19aa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
19ab0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
19ac0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
19ad0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
19ae0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
19af0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
19b00 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
19b10 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
19b20 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  HE],.** and/or [
19b30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
19b40 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a  ATECACHE] flags:
19b50 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
19b60 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
19b70 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
19b80 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
19b90 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
19ba0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
19bb0 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
19bc0 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
19bd0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
19be0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
19bf0 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
19c00 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
19c10 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
19c20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
19c30 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
19c40 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
19c50 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
19c60 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
19c70 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
19c80 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
19c90 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
19ca0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
19cb0 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
19cc0 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
19cd0 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
19ce0 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
19cf0 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
19d00 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
19d10 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
19d20 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
19d30 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
19d40 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
19d50 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
19d60 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
19d70 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
19d80 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
19d90 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
19da0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
19db0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
19dc0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
19dd0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
19de0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
19df0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
19e00 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
19e10 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
19e20 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
19e30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19e40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
19e50 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
19e60 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
19e70 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
19e80 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
19e90 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
19ea0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
19eb0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
19ec0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
19ed0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
19ee0 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
19ef0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
19f00 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
19f10 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
19f20 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  ACHE] flags,.** 
19f30 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
19f40 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
19f50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
19f60 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
19f70 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
19f80 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
19f90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
19fa0 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
19fb0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
19fc0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
19fd0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
19fe0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
19ff0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
1a000 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1a010 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1a020 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
1a030 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1a040 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1a050 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1a060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
1a070 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
1a080 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1a090 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
1a0a0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
1a0b0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
1a0c0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
1a0d0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1a0e0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
1a0f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1a100 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
1a110 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1a120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1a130 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
1a140 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
1a150 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
1a160 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1a170 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1a180 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
1a190 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1a1a0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1a1b0 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
1a1c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1a1d0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1a1e0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1a1f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a200 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
1a210 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
1a220 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1a230 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
1a240 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nabled..**.** ^I
1a250 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1a260 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1a270 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1a280 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
1a290 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
1a2a0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1a2b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
1a2c0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1a2d0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1a2e0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1a2f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a300 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1a310 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1a320 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1a330 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1a340 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1a350 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1a360 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1a370 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1a380 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1a390 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1a3a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1a3b0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1a3c0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1a3d0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1a3e0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1a3f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1a400 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1a410 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1a420 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1a430 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1a440 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1a450 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1a460 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1a470 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1a480 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1a490 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
1a4a0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1a4b0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1a4c0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1a4d0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1a4e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a4f0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1a500 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
1a510 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1a520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a530 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
1a540 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1a550 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
1a560 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
1a570 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1a580 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
1a590 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1a5a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
1a5b0 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
1a5c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1a5d0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1a5e0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1a5f0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1a600 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1a610 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
1a620 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
1a630 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
1a640 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
1a650 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
1a660 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
1a670 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1a680 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a690 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
1a6a0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
1a6b0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
1a6c0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
1a6d0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
1a6e0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
1a6f0 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
1a700 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
1a710 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
1a720 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
1a730 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
1a740 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1a750 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1a760 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1a770 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
1a780 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1a790 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1a7a0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1a7b0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1a7c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1a7d0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1a7e0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1a7f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
1a800 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
1a810 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
1a820 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
1a830 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
1a840 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1a850 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1a860 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1a870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1a880 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
1a890 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
1a8a0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
1a8b0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
1a8c0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1a8d0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
1a8e0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1a8f0 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
1a900 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
1a910 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
1a920 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
1a930 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
1a940 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
1a950 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
1a960 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
1a970 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
1a980 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
1a990 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1a9a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1a9b0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
1a9c0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
1a9d0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1a9e0 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1a9f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1aa00 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1aa10 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
1aa20 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1aa30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aa40 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
1aa50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
1aa60 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
1aa70 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
1aa80 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
1aa90 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
1aaa0 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
1aab0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
1aac0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1aad0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1aae0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
1aaf0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
1ab00 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
1ab10 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
1ab20 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1ab30 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
1ab40 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
1ab50 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
1ab60 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
1ab70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
1ab80 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
1ab90 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
1aba0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
1abb0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
1abc0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
1abd0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
1abe0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1abf0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1ac00 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
1ac10 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
1ac20 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
1ac30 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
1ac40 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
1ac50 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
1ac60 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
1ac70 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
1ac80 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
1ac90 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
1aca0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
1acb0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
1acc0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
1acd0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1ace0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
1acf0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1ad00 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ns.)^.**.** When
1ad10 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
1ad20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
1ad30 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d   is in use, it m
1ad40 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63  ight be the.** c
1ad50 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e  ase that a secon
1ad60 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f  d error occurs o
1ad70 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  n a separate thr
1ad80 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a  ead in between.*
1ad90 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68  * the time of th
1ada0 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e  e first error an
1adb0 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68  d the call to th
1adc0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ese interfaces..
1add0 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70  ** When that hap
1ade0 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64  pens, the second
1adf0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
1ae00 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68  eported since th
1ae10 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ese.** interface
1ae20 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20  s always report 
1ae30 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1ae40 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69  result.  To avoi
1ae50 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20  d.** this, each 
1ae60 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69  thread can obtai
1ae70 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20  n exclusive use 
1ae80 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
1ae90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
1aea0 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73  * by invoking [s
1aeb0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
1aec0 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  er]([sqlite3_db_
1aed0 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72  mutex](D)) befor
1aee0 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74  e beginning.** t
1aef0 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f  o use D and invo
1af00 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
1af10 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69  tex_leave]([sqli
1af20 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
1af30 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63  ) after.** all c
1af40 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65  alls to the inte
1af50 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65  rfaces listed he
1af60 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64  re are completed
1af70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
1af80 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
1af90 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
1afa0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1afb0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
1afc0 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
1afd0 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
1afe0 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
1aff0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
1b000 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
1b010 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
1b020 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f  y not be set..*/
1b030 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
1b040 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1b050 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
1b060 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1b070 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
1b080 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1b090 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
1b0a0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
1b0b0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1b0c0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1b0d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
1b0e0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
1b0f0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1b100 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b110 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
1b120 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
1b130 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
1b140 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
1b150 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
1b160 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
1b170 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
1b180 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
1b190 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
1b1a0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
1b1b0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
1b1c0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
1b1d0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
1b1e0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
1b1f0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
1b200 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
1b210 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
1b220 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
1b230 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
1b240 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1b250 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b260 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
1b270 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
1b280 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
1b290 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
1b2a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
1b2b0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
1b2c0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
1b2d0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
1b2e0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
1b2f0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
1b300 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
1b310 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
1b320 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
1b330 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
1b340 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
1b350 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
1b360 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
1b370 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
1b380 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
1b390 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
1b3a0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
1b3b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1b3c0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
1b3d0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
1b3e0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
1b3f0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
1b400 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
1b410 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1b420 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
1b430 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
1b440 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
1b450 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
1b460 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
1b470 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
1b480 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
1b490 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
1b4a0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
1b4b0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
1b4c0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
1b4d0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
1b4e0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
1b4f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1b500 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
1b510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b520 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
1b530 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
1b540 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
1b550 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
1b560 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
1b570 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
1b580 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
1b590 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
1b5a0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
1b5b0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
1b5c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
1b5d0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
1b5e0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
1b5f0 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74  ruct.  The funct
1b600 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
1b610 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a  old limit.)^.**.
1b620 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
1b630 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
1b640 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
1b650 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
1b660 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65 20  d..** ^(For the 
1b670 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
1b680 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
1b690 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  YZ there is a .*
1b6a0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
1b6b0 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
1b6c0 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c   set by a compil
1b6d0 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63  e-time C preproc
1b6e0 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65  essor macro name
1b6f0 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  d .** [limits | 
1b700 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e  SQLITE_MAX_XYZ].
1b710 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
1b720 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
1b730 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
1b740 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
1b750 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
1b760 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
1b770 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
1b780 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
1b790 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
1b7a0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
1b7b0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75   bound..**.** Ru
1b7c0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
1b7d0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
1b7e0 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
1b7f0 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
1b800 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
1b810 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
1b820 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
1b830 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
1b840 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
1b850 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
1b860 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
1b870 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
1b880 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
1b890 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
1b8a0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
1b8b0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
1b8c0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
1b8d0 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
1b8e0 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
1b8f0 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
1b900 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
1b910 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
1b920 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
1b930 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
1b940 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
1b950 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
1b960 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
1b970 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
1b980 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
1b990 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
1b9a0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
1b9b0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
1b9c0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
1b9d0 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
1b9e0 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
1b9f0 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
1ba00 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
1ba10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
1ba20 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
1ba30 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
1ba40 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
1ba50 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
1ba60 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
1ba70 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
1ba80 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
1ba90 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
1baa0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
1bab0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
1bac0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1bad0 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
1bae0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
1baf0 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
1bb00 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
1bb10 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
1bb20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
1bb30 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
1bb40 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
1bb50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1bb60 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1bb70 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
1bb80 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
1bb90 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
1bba0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1bbb0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1bbc0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
1bbd0 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
1bbe0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1bbf0 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
1bc00 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
1bc10 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1bc20 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
1bc30 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
1bc40 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1bc50 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
1bc60 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
1bc70 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
1bc80 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
1bc90 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
1bca0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
1bcb0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53   <dl>.** ^(<dt>S
1bcc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1bcd0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1bce0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
1bcf0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
1bd00 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
1bd10 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  ow.<dd>)^.**.** 
1bd20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1bd30 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
1bd40 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1bd50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1bd60 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1bd70 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
1bd80 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1bd90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1bda0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
1bdb0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1bdc0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1bdd0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
1bde0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
1bdf0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
1be00 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
1be10 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1be20 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
1be30 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
1be40 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
1be50 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
1be60 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1be70 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
1be80 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
1be90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1bea0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
1beb0 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
1bec0 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
1bed0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1bee0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1bef0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
1bf00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1bf10 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
1bf20 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
1bf30 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
1bf40 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
1bf50 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1bf60 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
1bf70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1bf80 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
1bf90 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
1bfa0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
1bfb0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
1bfc0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
1bfd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1bfe0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1bff0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c000 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
1c010 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1c020 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
1c030 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
1c040 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
1c050 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c060 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1c070 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c080 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c090 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
1c0a0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
1c0b0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e  .)^</dd>.**.** ^
1c0c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c0d0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1c0e0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1c0f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1c100 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1c110 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1c120 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
1c130 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
1c140 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1c150 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c160 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1c170 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
1c180 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1c190 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
1c1a0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1c1b0 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
1c1c0 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a  e bound.</dd>)^.
1c1d0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1c1e0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
1c1f0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1c200 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1c210 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
1c220 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
1c230 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1c240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c250 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
1c260 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c270 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
1c280 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
1c290 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
1c2a0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
1c2b0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
1c2c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c2d0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
1c2e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1c2f0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
1c300 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
1c310 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
1c320 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
1c330 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
1c340 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1c350 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
1c360 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
1c370 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
1c380 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
1c390 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
1c3a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
1c3b0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
1c3c0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
1c3d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c3e0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1c3f0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
1c400 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c410 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c420 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
1c430 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c440 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
1c450 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
1c460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1c470 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
1c480 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
1c490 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
1c4a0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
1c4b0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
1c4c0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
1c4d0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
1c4e0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
1c4f0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
1c500 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
1c510 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1c520 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
1c530 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
1c540 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
1c550 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
1c560 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
1c570 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
1c580 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1c590 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1c5a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
1c5b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
1c5c0 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
1c5d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c5e0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
1c5f0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
1c600 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
1c610 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
1c620 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
1c630 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
1c640 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
1c650 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
1c660 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
1c670 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
1c680 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1c690 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
1c6a0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
1c6b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1c6c0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
1c6d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1c6e0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
1c6f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1c700 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
1c710 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
1c720 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
1c730 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
1c740 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1c750 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
1c760 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1c770 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
1c780 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
1c790 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
1c7a0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
1c7b0 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
1c7c0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
1c7d0 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
1c7e0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
1c7f0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
1c800 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
1c810 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
1c820 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
1c830 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
1c840 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
1c850 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
1c860 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
1c870 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
1c880 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
1c890 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
1c8a0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
1c8b0 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
1c8c0 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
1c8d0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
1c8e0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
1c8f0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
1c900 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1c910 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
1c920 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
1c930 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
1c940 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  ator bytes..**.*
1c950 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
1c960 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
1c970 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1c980 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
1c990 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
1c9a0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
1c9b0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
1c9c0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
1c9d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
1c9e0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
1c9f0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
1ca00 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
1ca10 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
1ca20 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
1ca30 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
1ca40 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
1ca50 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
1ca60 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
1ca70 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
1ca80 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
1ca90 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
1caa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1cab0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
1cac0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
1cad0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
1cae0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
1caf0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
1cb00 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
1cb10 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
1cb20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
1cb30 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
1cb40 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
1cb50 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
1cb60 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1cb70 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1cb80 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1cb90 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
1cba0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1cbb0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1cbc0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1cbd0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1cbe0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
1cbf0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
1cc00 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
1cc10 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
1cc20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
1cc30 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
1cc40 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
1cc50 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
1cc60 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1cc70 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
1cc80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1cc90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
1cca0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1ccb0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
1ccc0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
1ccd0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
1cce0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
1ccf0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
1cd00 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
1cd10 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
1cd20 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1cd30 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
1cd40 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
1cd50 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
1cd60 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
1cd70 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
1cd80 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
1cd90 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
1cda0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
1cdb0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
1cdc0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
1cdd0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
1cde0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
1cdf0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1ce00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
1ce10 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
1ce20 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
1ce30 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
1ce40 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
1ce50 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1ce60 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
1ce70 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
1ce80 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1ce90 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
1cea0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
1ceb0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1cec0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
1ced0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
1cee0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1cef0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
1cf00 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74 68  t again.  ^If th
1cf10 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61  e schema has cha
1cf20 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79  nged in.** a way
1cf30 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20   that makes the 
1cf40 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e  statement no lon
1cf50 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69  ger valid, [sqli
1cf60 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1cf70 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e   still.** return
1cf80 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1cf90 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68  .  But unlike th
1cfa0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1cfb0 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  r, [SQLITE_SCHEM
1cfc0 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66  A] is.** now a f
1cfd0 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c  atal error.  Cal
1cfe0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
1cff0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69  epare_v2()] agai
1d000 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20  n will not make 
1d010 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20  the.** error go 
1d020 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65  away.  Note: use
1d030 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d040 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ()] to find the 
1d050 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70  text.** of the p
1d060 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61  arsing error tha
1d070 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20  t results in an 
1d080 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1d090 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e  return..** </li>
1d0a0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
1d0b0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
1d0c0 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
1d0d0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
1d0e0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
1d0f0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
1d100 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
1d110 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
1d120 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20  ].  ^The legacy 
1d130 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61  behavior was tha
1d140 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  t.** [sqlite3_st
1d150 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79  ep()] would only
1d160 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69   return a generi
1d170 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  c [SQLITE_ERROR]
1d180 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20   result code.** 
1d190 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
1d1a0 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74  ion would have t
1d1b0 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20  o make a second 
1d1c0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1d1d0 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20  _reset()].** in 
1d1e0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68  order to find th
1d1f0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75  e underlying cau
1d200 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65  se of the proble
1d210 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22  m. With the "v2"
1d220 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65   prepare.** inte
1d230 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65  rfaces, the unde
1d240 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f  rlying reason fo
1d250 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72  r the error is r
1d260 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1d270 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ely..** </li>.**
1d280 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1d290 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 5b  the value of a [
1d2a0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
1d2b0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
1d2c0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
1d2d0 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65 20  might.** change 
1d2e0 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20 66  the query plan f
1d2f0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  or a statement, 
1d300 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
1d310 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75 74  nt may be.** aut
1d320 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1d330 70 69 6c 65 64 20 28 61 73 20 69 66 20 74 68 65  piled (as if the
1d340 72 65 20 68 61 64 20 62 65 65 6e 20 61 20 73 63  re had been a sc
1d350 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e 20  hema change) on 
1d360 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b 73  the first .** [s
1d370 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
1d380 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
1d390 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65 20  y change to the 
1d3a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d3b0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
1d3c0 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61 6d  s] of the [param
1d3d0 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e  eter]. .** </li>
1d3e0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
1d3f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1d400 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d410 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1d420 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1d430 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1d440 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1d450 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1d460 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
1d470 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1d480 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1d490 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1d4a0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1d4b0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1d4c0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1d4d0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1d4e0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1d4f0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
1d500 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1d510 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1d520 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1d530 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1d540 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
1d550 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1d560 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1d570 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1d580 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1d590 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1d5a0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1d5b0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1d5c0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1d5d0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1d5e0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1d5f0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1d600 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1d610 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1d620 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1d630 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1d640 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1d650 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1d660 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1d670 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1d680 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
1d690 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1d6a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1d6b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1d6c0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1d6d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1d6e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1d6f0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1d700 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1d710 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1d720 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1d730 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1d740 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1d750 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1d760 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1d770 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1d780 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1d790 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1d7a0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1d7b0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1d7c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1d7d0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
1d7e0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1d7f0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1d800 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1d810 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
1d820 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1d830 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
1d840 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1d850 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1d860 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1d870 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1d880 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1d890 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1d8a0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1d8b0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1d8c0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
1d8d0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1d8e0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1d8f0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1d900 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1d910 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
1d920 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
1d930 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
1d940 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1d950 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73   to retrieve a s
1d960 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65  aved copy of the
1d970 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c   original.** SQL
1d980 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
1d990 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  eate a [prepared
1d9a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74   statement] if t
1d9b0 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61  hat statement wa
1d9c0 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73  s.** compiled us
1d9d0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
1d9e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d9f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
1da00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
1da10 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1da20 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1da30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1da40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1da50 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1da60 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
1da70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1da80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1da90 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
1daa0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1dab0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
1dac0 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
1dad0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
1dae0 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
1daf0 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
1db00 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
1db10 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
1db20 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
1db30 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
1db40 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
1db50 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
1db60 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1db70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1db80 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1db90 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1dba0 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1dbb0 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1dbc0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1dbd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1dbe0 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1dbf0 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1dc00 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1dc10 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1dc20 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1dc30 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1dc40 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1dc50 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1dc60 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1dc70 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1dc80 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1dc90 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1dca0 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1dcb0 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1dcc0 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1dcd0 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1dce0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
1dcf0 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
1dd00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1dd10 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
1dd20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
1dd30 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
1dd40 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
1dd50 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
1dd60 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
1dd70 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
1dd80 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
1dd90 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1dda0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ddb0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
1ddc0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
1ddd0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1dde0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ddf0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
1de00 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
1de10 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
1de20 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
1de30 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
1de40 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
1de50 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
1de60 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
1de70 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
1de80 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
1de90 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
1dea0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
1deb0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1dec0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1ded0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
1dee0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
1def0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
1df00 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1df10 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1df20 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1df30 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
1df40 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
1df50 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
1df60 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
1df70 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
1df80 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
1df90 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
1dfa0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
1dfb0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
1dfc0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
1dfd0 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
1dfe0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1dff0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1e000 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e010 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1e020 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1e030 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e040 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e050 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1e060 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1e070 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1e080 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1e090 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1e0a0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1e0b0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1e0c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1e0d0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1e0e0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1e0f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1e100 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1e110 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1e120 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e130 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1e140 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1e150 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1e160 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1e170 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1e180 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1e190 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1e1a0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1e1b0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1e1c0 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1e1d0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1e1e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e1f0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1e200 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1e210 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1e220 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1e230 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1e240 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
1e250 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1e260 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1e270 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1e280 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1e290 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1e2a0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1e2b0 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
1e2c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1e2d0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
1e2e0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
1e2f0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
1e300 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1e310 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
1e320 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
1e330 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1e340 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
1e350 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
1e360 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
1e370 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
1e380 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1e390 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
1e3a0 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
1e3b0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
1e3c0 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
1e3d0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
1e3e0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
1e3f0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
1e400 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
1e410 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
1e420 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
1e430 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1e440 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
1e450 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
1e460 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
1e470 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
1e480 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
1e490 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
1e4a0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
1e4b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
1e4c0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
1e4d0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
1e4e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1e4f0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
1e500 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
1e510 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
1e520 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
1e530 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
1e540 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1e550 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
1e560 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e570 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
1e580 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
1e590 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1e5a0 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
1e5b0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
1e5c0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
1e5d0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
1e5e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1e5f0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
1e600 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
1e610 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
1e620 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
1e630 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
1e640 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
1e650 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
1e660 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
1e670 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
1e680 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
1e690 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
1e6a0 20 69 64 65 6e 74 69 66 65 72 2e 29 5e 20 20 5e   identifer.)^  ^
1e6b0 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
1e6c0 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
1e6d0 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
1e6e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1e6f0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
1e700 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
1e710 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
1e720 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1e730 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
1e740 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
1e750 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1e760 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
1e770 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1e780 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
1e790 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
1e7a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
1e7b0 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
1e7c0 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
1e7d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e7e0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1e7f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
1e800 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
1e810 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1e820 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
1e830 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
1e840 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
1e850 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
1e860 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
1e870 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
1e880 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
1e890 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
1e8a0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
1e8b0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
1e8c0 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
1e8d0 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
1e8e0 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
1e8f0 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
1e900 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
1e910 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
1e920 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
1e930 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
1e940 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1e950 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
1e960 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
1e970 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
1e980 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
1e990 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
1e9a0 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
1e9b0 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
1e9c0 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
1e9d0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
1e9e0 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
1e9f0 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
1ea00 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1ea10 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
1ea20 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
1ea30 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
1ea40 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
1ea50 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
1ea60 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1ea70 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
1ea80 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
1ea90 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1eaa0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
1eab0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1eac0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
1ead0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
1eae0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
1eaf0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1eb00 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
1eb10 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
1eb20 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
1eb30 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
1eb40 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
1eb50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
1eb60 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67  gative, the leng
1eb70 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
1eb80 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   is.** the numbe
1eb90 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f  r of bytes up to
1eba0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1ebb0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1ebc0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
1ebd0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1ebe0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
1ebf0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1ec00 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
1ec10 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
1ec20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
1ec30 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
1ec40 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
1ec50 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
1ec60 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
1ec70 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66 20  ed with it. ^If 
1ec80 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1ec90 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
1eca0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
1ecb0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
1ecc0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
1ecd0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
1ece0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
1ecf0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
1ed00 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
1ed10 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
1ed20 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
1ed30 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1ed40 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1ed50 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1ed60 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1ed70 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1ed80 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1ed90 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1eda0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1edb0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1edc0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1edd0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1ede0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
1edf0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
1ee00 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
1ee10 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
1ee20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
1ee30 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
1ee40 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
1ee50 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
1ee60 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
1ee70 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
1ee80 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
1ee90 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
1eea0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
1eeb0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
1eec0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
1eed0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
1eee0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
1eef0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
1ef00 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
1ef10 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
1ef20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
1ef30 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
1ef40 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
1ef50 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
1ef60 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
1ef70 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
1ef80 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
1ef90 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
1efa0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1efb0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
1efc0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1efd0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
1efe0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1eff0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
1f000 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f010 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
1f020 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f030 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
1f040 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
1f050 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
1f060 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
1f070 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
1f080 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
1f090 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
1f0a0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
1f0b0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
1f0c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1f0d0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
1f0e0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
1f0f0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
1f100 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
1f110 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
1f120 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
1f130 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
1f140 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
1f150 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
1f160 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
1f170 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
1f180 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
1f190 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
1f1a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
1f1b0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
1f1c0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
1f1d0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
1f1e0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
1f1f0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
1f200 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
1f210 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
1f220 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
1f230 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
1f240 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
1f250 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
1f260 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
1f270 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
1f280 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1f290 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1f2a0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
1f2b0 2a 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 6e 61 6d 65 28 29  parameter_name()
1f2d0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1f2e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1f2f0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
1f300 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f310 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1f320 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
1f330 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
1f340 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1f350 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
1f360 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
1f370 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
1f380 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f390 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
1f3a0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
1f3b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f3c0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
1f3d0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
1f3e0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
1f3f0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
1f400 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1f410 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
1f420 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
1f430 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1f440 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
1f450 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
1f460 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1f470 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
1f480 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f490 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
1f4a0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1f4b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1f4c0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
1f4d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1f4e0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
1f4f0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
1f500 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
1f510 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1f520 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
1f530 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
1f540 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
1f550 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
1f560 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
1f570 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
1f580 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
1f590 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
1f5a0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1f5b0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
1f5c0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
1f5d0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
1f5e0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
1f5f0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
1f600 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
1f610 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
1f620 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
1f630 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
1f640 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1f650 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
1f660 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
1f670 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
1f680 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
1f690 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
1f6a0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
1f6b0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
1f6c0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
1f6d0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
1f6e0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
1f6f0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
1f700 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
1f710 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
1f720 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
1f730 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
1f740 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
1f750 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
1f760 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
1f770 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
1f780 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1f790 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1f7a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1f7b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1f7c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1f7d0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1f7e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f7f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
1f800 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f810 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1f820 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
1f830 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f840 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
1f850 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
1f860 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1f870 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1f880 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
1f890 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
1f8a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
1f8b0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
1f8c0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
1f8d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
1f8e0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
1f8f0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
1f900 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
1f910 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1f920 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
1f930 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
1f940 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
1f950 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
1f960 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
1f970 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1f980 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
1f990 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
1f9a0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
1f9b0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
1f9c0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
1f9d0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
1f9e0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
1f9f0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
1fa00 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
1fa10 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
1fa20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
1fa30 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
1fa40 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
1fa50 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
1fa60 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
1fa70 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
1fa80 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1fa90 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
1faa0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
1fab0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
1fac0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
1fad0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
1fae0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
1faf0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
1fb00 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
1fb10 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
1fb20 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
1fb30 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
1fb40 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
1fb50 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
1fb60 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
1fb70 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
1fb80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fb90 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
1fba0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1fbb0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
1fbc0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1fbd0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1fbe0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1fbf0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1fc00 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
1fc10 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1fc20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1fc30 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
1fc40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
1fc50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1fc60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1fc70 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
1fc80 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
1fc90 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
1fca0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
1fcb0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
1fcc0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
1fcd0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
1fce0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
1fcf0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
1fd00 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
1fd10 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
1fd20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
1fd30 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1fd40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1fd50 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
1fd60 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
1fd70 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
1fd80 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
1fd90 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
1fda0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
1fdb0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
1fdc0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
1fdd0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
1fde0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
1fdf0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
1fe00 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
1fe10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fe20 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1fe30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1fe40 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1fe50 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1fe60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1fe70 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1fe80 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1fe90 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1fea0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
1feb0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1fec0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
1fed0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
1fee0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
1fef0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ff00 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
1ff10 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
1ff20 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
1ff30 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
1ff40 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
1ff50 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
1ff60 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
1ff70 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
1ff80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1ff90 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
1ffa0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1ffb0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
1ffc0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
1ffd0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
1ffe0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
1fff0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
20000 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
20010 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
20020 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20030 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
20040 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
20050 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
20060 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
20070 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
20080 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
20090 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
200a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
200b0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
200c0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
200d0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
200e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
200f0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
20100 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
20110 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
20120 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20130 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
20140 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
20150 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
20160 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
20170 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
20180 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
20190 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
201a0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
201b0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
201c0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
201d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
201e0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
201f0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
20200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
20210 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
20220 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
20230 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
20240 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
20250 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
20260 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
20270 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
20280 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
20290 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
202a0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
202b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
202c0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
202d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
202e0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
202f0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
20300 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
20310 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
20320 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
20330 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
20340 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
20350 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
20360 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
20370 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
20380 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
20390 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
203a0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
203b0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
203c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
203d0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
203e0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
203f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
20400 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
20410 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
20420 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
20430 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
20440 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20450 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
20460 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
20470 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
20480 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
20490 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
204a0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
204b0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
204c0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
204d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
204e0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
204f0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
20500 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
20510 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
20520 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
20530 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
20540 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
20550 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
20560 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
20570 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20580 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
20590 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
205a0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
205b0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
205c0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
205d0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
205e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
205f0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
20600 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
20610 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
20620 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
20630 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
20640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20650 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
20660 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
20670 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
20680 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
20690 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
206a0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
206b0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
206c0 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
206d0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
206e0 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
206f0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
20700 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
20710 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
20720 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
20730 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
20740 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
20750 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
20760 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
20770 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
20780 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
20790 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
207a0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
207b0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
207c0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
207d0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
207e0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
207f0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
20800 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
20810 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
20820 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
20830 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
20840 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
20850 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
20860 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
20870 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
20880 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
20890 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
208a0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
208b0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
208c0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
208d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
208e0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
208f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
20900 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
20910 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
20920 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
20930 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
20940 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
20950 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
20960 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
20970 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
20980 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
20990 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
209a0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
209b0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
209c0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
209d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
209e0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
209f0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
20a00 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
20a10 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
20a20 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
20a30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
20a40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
20a50 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
20a60 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
20a70 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
20a80 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
20a90 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
20aa0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
20ab0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
20ac0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
20ad0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
20ae0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
20af0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
20b00 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
20b10 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
20b20 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
20b30 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
20b40 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
20b50 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
20b60 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
20b70 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
20b80 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
20b90 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
20ba0 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
20bb0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
20bc0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
20bd0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
20be0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
20bf0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
20c00 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
20c10 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
20c20 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
20c30 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
20c40 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
20c50 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
20c60 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
20c70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
20c80 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
20c90 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
20ca0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
20cb0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
20cc0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
20cd0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
20ce0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
20cf0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
20d00 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
20d10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
20d20 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
20d30 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
20d40 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
20d50 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
20d60 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
20d70 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
20d80 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
20d90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
20da0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
20db0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
20dc0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
20dd0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
20de0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20df0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
20e00 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
20e10 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
20e20 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
20e30 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
20e40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
20e50 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
20e60 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20e70 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
20e80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
20e90 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
20ea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20eb0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
20ec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20ed0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
20ee0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
20ef0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
20f00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
20f10 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
20f20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
20f30 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
20f40 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
20f50 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
20f60 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
20f70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
20f80 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
20f90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
20fa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20fb0 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
20fc0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
20fd0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
20fe0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
20ff0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
21000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
21010 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
21020 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
21030 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
21040 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
21050 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
21060 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
21070 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
21080 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
21090 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
210a0 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
210b0 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
210c0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
210d0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
210e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
210f0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
21100 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
21110 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
21120 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
21130 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
21140 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
21150 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
21160 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
21170 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
21180 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
21190 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
211a0 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
211b0 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
211c0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
211d0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
211e0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
211f0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
21200 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
21210 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
21220 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
21230 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
21240 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
21250 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
21260 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
21270 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
21280 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
21290 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
212a0 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
212b0 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
212c0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
212d0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
212e0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
212f0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
21300 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
21310 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
21320 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
21330 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
21340 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
21350 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
21360 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
21370 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
21380 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
21390 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
213a0 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
213b0 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
213c0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
213d0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
213e0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
213f0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
21400 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
21410 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
21420 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
21430 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
21440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
21450 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
21460 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
21470 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
21480 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
21490 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
214a0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
214b0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
214c0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
214d0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
214e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
214f0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
21500 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
21510 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
21520 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
21530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21540 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
21550 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
21560 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
21570 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
21580 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
21590 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
215a0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
215b0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
215c0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
215d0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
215e0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
215f0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
21600 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
21610 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
21620 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
21630 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
21640 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
21650 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
21660 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
21670 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
21680 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21690 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
216a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
216b0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
216c0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
216d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
216e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
216f0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
21700 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
21710 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
21720 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
21730 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
21740 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
21750 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
21760 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
21770 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
21780 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
21790 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
217a0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
217b0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
217c0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
217d0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
217e0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
217f0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
21800 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
21810 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
21820 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21830 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
21840 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
21850 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
21860 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
21870 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
21880 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
21890 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
218a0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
218b0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
218c0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
218d0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
218e0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
218f0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
21900 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
21910 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
21920 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
21930 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
21940 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
21950 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
21960 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
21970 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
21980 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
21990 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
219a0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
219b0 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74   a.** explicit t
219c0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
219d0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
219e0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
219f0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
21a00 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
21a10 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
21a20 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
21a30 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
21a40 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
21a50 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
21a60 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21a70 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
21a80 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
21a90 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
21aa0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
21ab0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
21ac0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
21ad0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
21ae0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
21af0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
21b00 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
21b10 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
21b20 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
21b30 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
21b40 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
21b50 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
21b60 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
21b70 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
21b80 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
21b90 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
21ba0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
21bb0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
21bc0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
21bd0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
21be0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
21bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
21c00 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
21c10 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
21c20 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
21c30 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
21c40 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
21c50 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
21c60 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
21c70 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
21c80 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
21c90 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
21ca0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
21cb0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
21cc0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
21cd0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
21ce0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
21cf0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
21d00 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
21d10 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
21d20 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
21d30 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
21d40 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
21d50 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
21d60 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
21d70 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
21d80 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
21d90 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
21da0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
21db0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
21dc0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
21dd0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
21de0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
21df0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
21e00 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
21e10 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
21e20 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
21e30 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
21e40 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
21e50 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
21e60 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
21e70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
21e80 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
21e90 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
21ea0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
21eb0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
21ec0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
21ed0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
21ee0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
21ef0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
21f00 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
21f10 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
21f20 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
21f30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
21f40 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
21f50 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
21f60 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
21f70 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
21f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
21f90 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
21fa0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
21fb0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
21fc0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
21fd0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
21fe0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
21ff0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
22000 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
22010 20 69 74 20 77 61 73 20 72 65 71 75 69 72 65 64   it was required
22020 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74 65  .** after sqlite
22030 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
22040 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  d anything other
22050 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
22060 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  W] that.** [sqli
22070 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65 20  te3_reset()] be 
22080 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61 6e  called before an
22090 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
220a0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
220b0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
220c0 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b 65  ailure to invoke
220d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
220e0 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20 77  )] in this way w
220f0 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ould.** result i
22100 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
22110 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
22120 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
22130 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20 76    But after.** v
22140 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
22150 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22160 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b 73  began calling [s
22170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22180 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
22190 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
221a0 73 74 61 6e 63 65 20 72 61 74 68 65 72 20 74 68  stance rather th
221b0 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
221c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 0a  LITE_MISUSE].  .
221d0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
221e0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
221f0 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
22200 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
22210 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
22220 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
22230 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
22240 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
22250 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
22260 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
22270 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
22280 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
22290 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
222a0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
222b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
222c0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
222d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
222e0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
222f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
22300 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
22310 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
22320 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
22330 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
22340 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
22350 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
22360 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
22370 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
22380 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
22390 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
223a0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
223b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
223c0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
223d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
223e0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
223f0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22400 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
22410 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
22420 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
22430 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
22440 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
22450 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
22460 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
22470 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
22480 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
22490 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
224a0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
224b0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
224c0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
224d0 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
224e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
224f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
22500 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
22510 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
22520 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
22530 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22540 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
22550 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
22560 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
22570 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
22580 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
22590 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f  statement] P..*/
225a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74  .int sqlite3_dat
225b0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
225c0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
225d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
225e0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
225f0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
22600 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
22610 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
22620 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
22630 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
22640 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
22650 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
22660 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
22670 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
22680 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
22690 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
226a0 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
226b0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
226c0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
226d0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
226e0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
226f0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
22700 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
22710 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
22720 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
22730 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
22740 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
22750 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
22760 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
22770 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
22780 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
22790 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
227a0 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
227b0 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
227c0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
227d0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
227e0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
227f0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
22800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
22810 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
22820 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
22830 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
22840 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
22850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
22860 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
22870 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
22880 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
22890 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
228a0 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
228b0 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
228c0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
228d0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
228e0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
228f0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
22900 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
22910 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
22920 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
22930 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
22940 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
22950 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
22960 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
22970 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
22980 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
22990 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
229a0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
229b0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
229c0 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
229d0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
229e0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
229f0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
22a00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22a10 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
22a20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
22a30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
22a40 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
22a50 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
22a60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22a70 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
22a80 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
22a90 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
22aa0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
22ab0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
22ac0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
22ad0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
22ae0 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
22af0 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
22b00 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
22b10 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
22b20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
22b30 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
22b40 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
22b50 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
22b60 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
22b70 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
22b80 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
22b90 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
22ba0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
22bb0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
22bc0 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
22bd0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
22be0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
22bf0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
22c00 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
22c10 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
22c20 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
22c30 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
22c40 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
22c50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
22c60 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
22c70 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
22c80 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
22c90 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
22ca0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22cb0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
22cc0 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
22cd0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
22ce0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
22cf0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
22d00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22d10 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
22d20 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
22d30 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
22d40 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
22d50 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
22d60 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
22d70 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
22d80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
22d90 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
22da0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
22db0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
22dc0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
22dd0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
22de0 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
22df0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
22e00 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
22e10 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
22e20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
22e30 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
22e40 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
22e50 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
22e60 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
22e70 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
22e80 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
22e90 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
22ea0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
22eb0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
22ec0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
22ed0 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
22ee0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
22ef0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
22f00 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
22f10 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
22f20 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
22f30 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
22f40 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
22f50 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
22f60 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
22f70 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
22f80 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
22f90 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
22fa0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
22fb0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
22fc0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
22fd0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
22fe0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
22ff0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
23000 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
23010 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
23020 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
23030 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
23040 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
23050 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
23060 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
23070 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
23080 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
23090 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
230a0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
230b0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
230c0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
230d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
230e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
230f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
23100 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
23110 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
23120 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
23130 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
23140 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
23150 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
23160 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
23170 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
23180 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
23190 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
231a0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
231b0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
231c0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
231d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
231e0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
231f0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
23200 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
23210 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
23220 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
23230 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
23240 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
23250 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
23260 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
23270 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
23280 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
23290 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20  rminator at the 
232a0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
232b0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
232c0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
232d0 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
232e0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
232f0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
23300 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
23310 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
23320 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
23330 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
23340 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
23350 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
23360 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
23370 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
23380 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
23390 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
233a0 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
233b0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
233c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
233d0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
233e0 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72  th BLOB is an ar
233f0 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74  bitrary.** point
23400 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65  er, possibly eve
23410 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
23420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
23430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23440 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73  s16() routine is
23450 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69   similar to sqli
23460 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23470 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73  ().** but leaves
23480 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55   the result in U
23490 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20  TF-16 in native 
234a0 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
234b0 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20  ad of UTF-8..** 
234c0 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ^The zero termin
234d0 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
234e0 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
234f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  nt..**.** ^The o
23500 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
23510 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
23520 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
23530 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
23540 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
23550 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72  object.  An unpr
23560 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
23570 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20  value object.** 
23580 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
23590 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62   with [sqlite3_b
235a0 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
235b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
235c0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
235d0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
235e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
235f0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
23600 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
23610 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
23620 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
23630 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
23640 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
23650 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
23660 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
23670 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
23680 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
23690 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
236a0 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e  e_bytes()], then
236b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
236c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
236d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
236e0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
236f0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68  ert the value wh
23700 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e  ere appropriate.
23710 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c    ^For.** exampl
23720 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e  e, if the intern
23730 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
23740 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61  n is FLOAT and a
23750 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20   text result.** 
23760 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73  is requested, [s
23770 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
23780 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  )] is used inter
23790 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d  nally to perform
237a0 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69   the.** conversi
237b0 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  on automatically
237c0 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69  .  ^(The followi
237d0 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73  ng table details
237e0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73   the conversions
237f0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70  .** that are app
23800 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lied:.**.** <blo
23810 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
23820 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
23830 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72  * <tr><th> Inter
23840 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  nal<br>Type <th>
23850 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79   Requested<br>Ty
23860 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73  pe <th>  Convers
23870 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
23880 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
23890 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
238a0 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c  Result is 0.** <
238b0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
238c0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
238d0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
238e0 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  .0.** <tr><td>  
238f0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54  NULL    <td>   T
23900 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  EXT    <td> Resu
23910 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
23920 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
23930 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
23940 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
23950 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74  lt is NULL point
23960 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
23970 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
23980 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
23990 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
239a0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
239b0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
239c0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
239d0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
239e0 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
239f0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
23a00 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
23a10 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
23a20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
23a30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
23a40 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
23a50 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
23a60 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20  t from float to 
23a70 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
23a80 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
23a90 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
23aa0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
23ab0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
23ac0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
23ad0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
23ae0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46    <td> Same as F
23af0 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  LOAT->TEXT.** <t
23b00 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
23b10 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
23b20 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a  td> Use atoi().*
23b30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
23b40 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
23b50 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66     <td> Use atof
23b60 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23b70 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
23b80 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
23b90 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
23ba0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
23bb0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
23bc0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
23bd0 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a  hen use atoi().*
23be0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
23bf0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
23c00 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
23c10 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
23c20 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
23c30 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
23c40 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
23c50 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
23c60 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
23c70 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
23c80 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
23c90 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
23ca0 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
23cb0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
23cc0 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
23cd0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
23ce0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
23cf0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
23d00 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
23d10 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
23d20 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
23d30 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
23d40 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
23d50 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
23d60 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
23d70 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
23d80 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
23d90 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
23da0 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
23db0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
23dc0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  rs..**.** ^Note 
23dd0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
23de0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
23df0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
23e00 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
23e10 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
23e20 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
23e30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23e40 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
23e50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23e60 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
23e70 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
23e80 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  ^(Type conversio
23e90 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
23ea0 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
23eb0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
23ec0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
23ed0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
23ee0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
23ef0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
23f00 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
23f10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
23f20 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
23f30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
23f40 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
23f50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
23f60 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
23f70 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
23f80 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
23f90 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
23fa0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
23fb0 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
23fc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23fd0 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
23fe0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
23ff0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
24000 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
24010 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
24020 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
24030 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
24040 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
24050 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
24060 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
24070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24080 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
24090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
240a0 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
240b0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
240c0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
240d0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
240e0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29  .</li>.** </ul>)
240f0 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  ^.**.** ^Convers
24100 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
24110 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
24120 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
24130 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
24140 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
24150 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
24160 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
24170 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
24180 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
24190 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
241a0 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
241b0 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
241c0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
241d0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
241e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
241f0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
24200 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
24210 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
24220 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
24230 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
24240 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
24250 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
24260 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
24270 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73 74 20  ** ^(The safest 
24280 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
24290 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
242a0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
242b0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
242c0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
242d0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
242e0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
242f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24300 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
24310 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24320 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
24330 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
24340 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
24350 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
24360 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
24370 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
24380 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
24390 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
243a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
243b0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
243c0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e  </ul>)^.**.** In
243d0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
243e0 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
243f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24400 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
24410 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
24420 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
24430 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
24440 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
24450 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
24460 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
24470 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
24480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24490 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
244a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
244b0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
244c0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
244d0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
244e0 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
244f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
24500 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
24510 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
24520 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
24530 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
24540 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
24550 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
24560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24570 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
24580 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
24590 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
245a0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73  ** ^The pointers
245b0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61   returned are va
245c0 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65  lid until a type
245d0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
245e0 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62  rs as.** describ
245f0 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74  ed above, or unt
24600 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  il [sqlite3_step
24610 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
24620 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
24630 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
24640 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  ()] is called.  
24650 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63  ^The memory spac
24660 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73  e used to hold s
24670 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c  trings.** and BL
24680 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74  OBs is freed aut
24690 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20  omatically.  Do 
246a0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20  <b>not</b> pass 
246b0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
246c0 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  urned.** [sqlite
246d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
246e0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
246f0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
24700 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
24710 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
24720 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
24730 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
24740 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
24750 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
24760 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
24770 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
24780 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
24790 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
247a0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
247b0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
247c0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
247d0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
247e0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
247f0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
24800 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
24810 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
24820 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
24830 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
24840 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
24850 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
24860 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
24870 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
24890 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
248a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
248b0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
248c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
248d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
248e0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
248f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
24900 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
24910 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24920 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
24930 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
24940 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24950 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
24960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
24970 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
24980 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
24990 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
249a0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
249b0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
249c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
249d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
249e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
249f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
24a00 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
24a10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24a20 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
24a30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
24a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
24a50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
24a60 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
24a70 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
24a80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
24a90 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
24aa0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
24ab0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
24ac0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
24ad0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
24ae0 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
24af0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24b00 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
24b10 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78  statement was ex
24b20 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
24b30 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  lly or not execu
24b40 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
24b50 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  .** SQLITE_OK is
24b60 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65   returned. ^If e
24b70 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
24b80 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64  statement failed
24b90 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72   then an.** [err
24ba0 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  or code] or [ext
24bb0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
24bc0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
24bd0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
24be0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
24bf0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
24c00 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
24c10 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
24c20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24c30 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69 72 74  ].  ^If the virt
24c40 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20  ual machine has 
24c50 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  not.** completed
24c60 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20   execution when 
24c70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
24c80 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20  called, that is 
24c90 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  like.** encounte
24ca0 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72  ring an error or
24cb0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
24cc0 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
24cd0 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c  pt]..** ^Incompl
24ce0 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79 20  ete updates may 
24cf0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
24d00 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  nd transactions 
24d10 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70  canceled,.** dep
24d20 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69  ending on the ci
24d30 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64  rcumstances, and
24d40 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63   the.** [error c
24d50 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69  ode] returned wi
24d60 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42  ll be [SQLITE_AB
24d70 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ORT]..*/.int sql
24d80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
24d90 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
24da0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
24db0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
24dc0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
24dd0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
24de0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
24df0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
24e00 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
24e10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24e20 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
24e30 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
24e40 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
24e50 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
24e60 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
24e70 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
24e80 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
24e90 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
24ea0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
24eb0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
24ec0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
24ed0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
24ee0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
24ef0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
24f00 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
24f10 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
24f20 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
24f30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24f40 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
24f50 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
24f60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
24f70 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
24f80 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
24f90 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
24fa0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
24fb0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
24fc0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
24fd0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
24fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
24ff0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
25000 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
25010 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
25020 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
25030 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
25040 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
25050 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
25060 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
25070 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
25080 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
25090 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
250a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
250b0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
250c0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
250d0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
250e0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
250f0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
25100 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
25110 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
25120 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
25130 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
25140 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
25150 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
25160 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
25170 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
25180 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
25190 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
251a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
251b0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
251c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
251d0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
251e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
251f0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
25200 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
25210 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
25220 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
25230 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
25240 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
25250 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25260 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
25270 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
25280 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
252a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f  **.** ^These two
252b0 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
252c0 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
252d0 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
252e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
252f0 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
25300 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
25310 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
25320 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
25330 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
25340 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
25350 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
25360 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
25370 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77   difference betw
25380 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69  een the.** two i
25390 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
253a0 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  d parameter, the
253b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63   name of the (sc
253c0 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f  alar) function o
253d0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20  r.** aggregate, 
253e0 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  is encoded in UT
253f0 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  F-8 for sqlite3_
25400 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
25410 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20  ) and UTF-16.** 
25420 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
25430 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e  te_function16().
25440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
25450 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
25460 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25470 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
25480 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
25490 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
254a0 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
254b0 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
254c0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
254d0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
254e0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
254f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
25500 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
25510 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
25520 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
25530 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
25540 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ly..**.** The se
25550 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
25560 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25570 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
25580 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
25590 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
255a0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
255b0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
255c0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20  d to 255 bytes, 
255d0 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20  exclusive of.** 
255e0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
255f0 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  tor.  Note that 
25600 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20  the name length 
25610 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65  limit is in byte
25620 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63  s, not.** charac
25630 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65  ters.  ^Any atte
25640 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
25650 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
25660 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
25670 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
25680 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69  QLITE_ERROR] bei
25690 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
256a0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
256b0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
256c0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
256d0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
256e0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
256f0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
25700 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
25710 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
25720 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
25730 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
25740 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
25750 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
25760 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
25770 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
25780 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
25790 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
257a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
257b0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
257c0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
257d0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
257e0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
257f0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
25800 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
25810 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
25820 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
25830 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
25840 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
25850 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
25860 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
25870 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
25880 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
25890 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
258a0 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
258b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
258c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
258d0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
258e0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
258f0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
25900 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
25910 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
25920 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
25930 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
25940 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
25950 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
25960 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
25970 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
25980 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25990 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
259a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
259b0 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
259c0 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
259d0 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
259e0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
259f0 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
25a00 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
25a10 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
25a20 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
25a30 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
25a40 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
25a50 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
25a60 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
25a70 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
25a80 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
25a90 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
25aa0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
25ab0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
25ac0 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
25ad0 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
25ae0 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
25af0 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
25b00 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
25b10 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
25b20 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
25b30 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
25b40 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
25b50 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
25b60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
25b70 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
25b80 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
25b90 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
25ba0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
25bb0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
25bc0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65  ^.**.** The seve
25bd0 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20  nth, eighth and 
25be0 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73  ninth parameters
25bf0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
25c00 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
25c10 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
25c20 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
25c30 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
25c40 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
25c50 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
25c60 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
25c70 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
25c80 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
25c90 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
25ca0 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
25cb0 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
25cc0 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  rs should be pas
25cd0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
25ce0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
25cf0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
25d00 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
25d10 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
25d20 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
25d30 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
25d40 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
25d50 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
25d60 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
25d70 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
25d80 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
25d90 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
25da0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
25db0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
25dc0 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
25dd0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
25de0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
25df0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
25e00 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
25e10 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
25e20 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
25e30 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
25e40 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
25e50 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
25e60 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
25e70 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
25e80 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
25e90 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
25ea0 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
25eb0 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
25ec0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
25ed0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
25ee0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
25ef0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
25f00 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
25f10 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
25f20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
25f30 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
25f40 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
25f50 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
25f60 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
25f70 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
25f80 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
25f90 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
25fa0 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
25fb0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
25fc0 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
25fd0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
25fe0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
25ff0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
26000 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
26010 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
26020 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
26030 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
26040 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
26050 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
26060 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
26070 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
26080 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
26090 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
260a0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
260b0 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
260c0 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
260d0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
260e0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
260f0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
26100 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
26110 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
26120 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
26130 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26140 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  ned function wit
26150 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f  h a given name o
26160 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20  verrides all.** 
26170 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  built-in functio
26180 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b  ns in the same [
26190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
261a0 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61  ion] with the sa
261b0 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62  me name..** ^Sub
261c0 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74  sequent applicat
261d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
261e0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
261f0 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72  e name only over
26200 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61  ride .** prior a
26210 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26220 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ed functions tha
26230 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d  t are an exact m
26240 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20  atch for the.** 
26250 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
26260 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72 72  ters and preferr
26270 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  ed encoding..**.
26280 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
26290 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
262a0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
262b0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
262c0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
262d0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
262e0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
262f0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
26300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26310 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
26320 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
26330 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
26340 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
26350 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
26360 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
26370 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26380 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
26390 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
263a0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
263b0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
263c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
263d0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
263e0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
263f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
26400 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
26410 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
26420 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
26430 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
26440 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
26450 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
26460 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
26470 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
26480 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
26490 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
264a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
264b0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
264c0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
264d0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
264e0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
264f0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
26500 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
26510 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
26520 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
26530 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
26540 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
26550 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
26560 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
26570 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
26580 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
26590 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54  ncodings.**.** T
265a0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65  hese constant de
265b0 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64  fine integer cod
265c0 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e  es that represen
265d0 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a  t the various.**
265e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20   text encodings 
265f0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c  supported by SQL
26600 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
26610 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20  SQLITE_UTF8     
26620 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
26630 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
26640 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
26650 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
26660 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
26670 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
26680 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
26690 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
266a0 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
266b0 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
266c0 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c       5    /* sql
266d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
266e0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65  tion only */.#de
266f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
26700 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
26710 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
26720 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
26730 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
26740 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
26750 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
26760 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
26770 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
26780 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
26790 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
267a0 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
267b0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
267c0 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
267d0 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
267e0 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
267f0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
26800 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
26810 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
26820 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
26830 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
26840 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20  tions.  To help 
26850 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65  encourage people
26860 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69   to avoid.** usi
26870 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ng these functio
26880 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67  ns, we are not g
26890 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75  oing to tell you
268a0 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a   what they do..*
268b0 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
268c0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44  _OMIT_DEPRECATED
268d0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
268e0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
268f0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
26900 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
26910 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
26920 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
26930 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
26940 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
26950 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
26960 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
26970 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
26980 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
26990 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
269a0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
269b0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
269c0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
269d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
269e0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
269f0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
26a00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
26a10 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65  D int sqlite3_me
26a20 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28  mory_alarm(void(
26a30 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
26a40 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64  _int64,int),void
26a50 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
26a60 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
26a70 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
26a80 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ing SQL Function
26a90 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65   Parameter Value
26aa0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  s.**.** The C-la
26ab0 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
26ac0 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
26ad0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
26ae0 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
26af0 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
26b00 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
26b10 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
26b20 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
26b30 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
26b40 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a  r aggregate..**.
26b50 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
26b60 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
26b70 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
26b80 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
26b90 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
26ba0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26bb0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
26bc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26bd0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
26be0 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
26bf0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
26c00 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
26c10 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
26c20 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72  ..** The 4th par
26c30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
26c40 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
26c50 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
26c60 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
26c70 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
26c80 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
26c90 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
26ca0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
26cb0 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
26cc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
26cd0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
26ce0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
26cf0 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
26d00 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
26d10 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
26d20 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
26d30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26d40 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
26d50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26d60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
26d70 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
26d80 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
26d90 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
26da0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26db0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
26dc0 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
26dd0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
26de0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
26df0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
26e00 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
26e10 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
26e20 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
26e30 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
26e40 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
26e50 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
26e60 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
26e70 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
26e80 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
26e90 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
26ea0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
26eb0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
26ec0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
26ed0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26ee0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
26ef0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
26f00 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
26f10 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
26f20 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
26f30 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
26f40 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
26f50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26f60 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
26f70 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
26f80 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
26f90 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
26fa0 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
26fb0 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
26fc0 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
26fd0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
26fe0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
26ff0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
27000 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
27010 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
27020 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
27030 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
27040 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
27050 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
27060 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
27070 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
27080 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
27090 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
270a0 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
270b0 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
270c0 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
270d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
270e0 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
270f0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
27100 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
27110 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
27120 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
27130 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
27140 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
27150 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
27160 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
27170 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
27180 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
27190 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
271a0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
271b0 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
271c0 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
271d0 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
271e0 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
271f0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
27200 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
27210 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
27220 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
27230 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
27240 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
27250 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
27260 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
27270 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
27280 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
27290 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
272a0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
272b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
272c0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
272d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
272e0 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
272f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
27300 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
27310 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
27320 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
27330 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
27340 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
27350 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
27360 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
27370 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
27380 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
27390 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
273a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
273b0 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
273c0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
273d0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
273e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
273f0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
27400 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
27410 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
27420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
27430 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
27440 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
27450 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
27460 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
27470 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
27480 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
27490 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
274a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
274b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
274c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
274d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
274e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
274f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27500 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
27510 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
27520 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
27530 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
27540 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
27550 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
27560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27570 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
27580 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
27590 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
275a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
275b0 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
275c0 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
275d0 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
275e0 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  entions of aggre
275f0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
27600 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
27610 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
27620 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
27630 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
27640 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
27650 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
27660 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27670 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
27680 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
27690 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
276a0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
276b0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
276c0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
276d0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
276e0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
276f0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
27700 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
27710 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
27720 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
27730 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
27740 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
27750 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
27760 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
27770 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
27780 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
27790 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
277a0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
277b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
277c0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
277d0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
277e0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
277f0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
27800 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
27810 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
27820 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
27830 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
27840 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
27850 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
27860 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
27870 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
27880 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
27890 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
278a0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
278b0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
278c0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
278d0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
278e0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
278f0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
27900 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27910 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
27920 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
27930 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
27940 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
27950 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
27960 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
27970 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
27980 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
27990 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
279a0 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
279b0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
279c0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
279d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
279e0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
279f0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
27a00 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
27a10 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
27a20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27a30 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
27a40 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
27a50 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
27a60 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
27a70 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
27a80 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
27a90 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
27aa0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
27ab0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27ac0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
27ad0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
27ae0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
27af0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
27b00 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
27b10 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
27b20 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
27b30 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
27b40 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
27b50 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
27b60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27b70 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
27b80 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
27b90 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
27ba0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
27bb0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
27bc0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
27bd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
27be0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
27bf0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
27c00 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
27c10 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
27c20 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
27c30 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
27c40 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
27c50 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
27c60 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
27c70 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
27c80 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
27c90 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
27ca0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
27cb0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
27cc0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
27cd0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
27ce0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27cf0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
27d00 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
27d10 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
27d20 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
27d30 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
27d40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27d50 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
27d60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
27d70 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
27d80 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
27d90 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
27da0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
27db0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
27dc0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
27dd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
27de0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
27df0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
27e00 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
27e10 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
27e20 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
27e30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
27e40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
27e50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
27e60 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
27e70 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
27e80 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
27e90 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
27ea0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
27eb0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
27ec0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
27ed0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
27ee0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
27ef0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27f00 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
27f10 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
27f20 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
27f30 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
27f40 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
27f50 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
27f60 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
27f70 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
27f80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
27f90 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
27fa0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
27fb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27fc0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
27fd0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
27fe0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
27ff0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
28000 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
28010 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
28020 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
28030 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
28040 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
28050 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
28060 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
28070 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28080 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
28090 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
280a0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
280b0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
280c0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
280d0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
280e0 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
280f0 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
28100 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
28110 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
28120 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
28130 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
28140 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
28150 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
28160 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
28170 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
28180 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
28190 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
281a0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
281b0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
281c0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
281d0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
281e0 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
281f0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
28200 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
28210 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
28220 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
28230 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
28240 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
28250 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
28260 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
28270 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
28280 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
28290 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
282a0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
282b0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
282c0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
282d0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
282e0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
282f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
28300 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
28310 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
28320 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
28330 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
28340 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
28350 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
28360 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
28370 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28380 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
28390 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
283a0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
283b0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
283c0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
283d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
283e0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
283f0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
28400 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
28410 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28420 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
28430 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
28440 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
28450 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
28460 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
28470 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
28480 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
28490 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
284a0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
284b0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
284c0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
284d0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
284e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
284f0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
28500 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
28510 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
28520 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
28530 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
28540 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
28550 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
28560 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
28570 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
28580 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
28590 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
285a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
285b0 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
285c0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
285d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
285e0 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
285f0 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
28600 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
28610 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
28620 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
28630 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
28640 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
28650 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
28660 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
28670 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28680 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
28690 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
286a0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
286b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
286c0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
286d0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
286e0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
286f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
28700 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
28710 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
28720 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
28730 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
28740 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
28750 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
28760 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
28770 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
28780 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
28790 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
287a0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
287b0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
287c0 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
287d0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
287e0 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
287f0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
28800 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
28810 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
28820 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
28830 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
28840 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
28850 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
28860 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
28870 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
28880 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
28890 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
288a0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
288b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
288c0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
288d0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
288e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
288f0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
28900 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
28910 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
28920 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
28930 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
28940 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
28950 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
28960 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
28970 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
28980 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
28990 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
289a0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
289b0 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
289c0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
289d0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
289e0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
289f0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
28a00 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
28a10 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
28a20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
28a30 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
28a40 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
28a50 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
28a60 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
28a70 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
28a80 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
28a90 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
28aa0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
28ab0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
28ac0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
28ad0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
28ae0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
28af0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
28b00 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
28b10 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
28b20 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
28b30 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
28b40 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
28b50 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
28b60 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
28b70 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
28b80 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
28b90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
28ba0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
28bb0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
28bc0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
28bd0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
28be0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
28bf0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
28c00 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
28c10 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
28c20 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
28c30 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
28c40 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
28c50 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
28c60 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
28c70 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
28c80 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
28c90 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
28ca0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
28cb0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
28cc0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
28cd0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
28ce0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
28cf0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
28d00 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
28d10 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
28d20 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
28d30 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
28d40 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
28d50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
28d60 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
28d70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
28d80 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
28d90 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
28da0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
28db0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
28dc0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
28dd0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
28de0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
28df0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
28e00 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
28e10 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
28e20 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
28e30 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
28e40 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
28e50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
28e60 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
28e70 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
28e80 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
28e90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
28ea0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
28eb0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
28ec0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
28ed0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28ee0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
28ef0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
28f00 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
28f10 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
28f20 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
28f30 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
28f40 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
28f50 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
28f60 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
28f70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28f80 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
28f90 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
28fa0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
28fb0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
28fc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
28fd0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
28fe0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
28ff0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
29000 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
29010 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
29020 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
29030 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
29040 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29050 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
29060 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
29070 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
29080 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
29090 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
290a0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
290b0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
290c0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
290d0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
290e0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
290f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29100 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
29110 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29120 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
29130 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
29140 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
29150 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
29160 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
29170 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
29180 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
29190 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
291a0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
291b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
291c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
291d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
291e0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
291f0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
29200 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
29210 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
29220 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
29230 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
29240 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
29250 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
29260 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
29270 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
29280 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29290 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
292a0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
292b0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
292c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
292d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
292e0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
292f0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
29300 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
29310 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
29320 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
29330 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
29340 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
29350 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
29360 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
29370 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
29380 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29390 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
293a0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
293b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
293c0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
293d0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
293e0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
293f0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
29400 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
29410 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
29420 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
29430 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
29440 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29450 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
29460 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29470 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
29480 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
29490 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
294a0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
294b0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
294c0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
294d0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
294e0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
294f0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
29500 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
29510 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
29520 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
29530 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29540 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
29550 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
29560 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
29570 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
29580 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
29590 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
295a0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
295b0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
295c0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
295d0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
295e0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
295f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29600 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
29610 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29620 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
29630 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
29640 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
29650 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29660 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
29670 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
29680 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
29690 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
296a0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
296b0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
296c0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
296d0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
296e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
296f0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
29700 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
29710 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
29720 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
29730 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
29740 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
29750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29760 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
29770 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
29780 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
29790 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
297a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
297b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
297c0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
297d0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
297e0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
297f0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
29800 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29810 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
29820 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
29830 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
29840 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29850 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
29860 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
29870 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
29880 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
29890 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
298a0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
298b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
298c0 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
298d0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
298e0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
298f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29900 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
29910 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
29920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29930 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
29940 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
29950 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
29960 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
29970 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
29980 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
29990 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
299a0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
299b0 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
299c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
299d0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
299e0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
299f0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
29a00 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
29a10 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
29a20 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
29a30 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
29a40 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
29a50 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
29a60 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
29a70 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
29a80 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
29a90 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
29aa0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
29ab0 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
29ac0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
29ad0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
29ae0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
29af0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
29b00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29b10 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
29b20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
29b30 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
29b40 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
29b50 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
29b60 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
29b70 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
29b80 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
29b90 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
29ba0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
29bb0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29bc0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
29bd0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
29be0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
29bf0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
29c00 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
29c10 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
29c20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
29c30 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
29c40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29c50 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
29c60 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
29c70 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
29c80 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
29c90 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29ca0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
29cb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
29cc0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
29cd0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
29ce0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
29cf0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
29d00 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
29d10 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
29d20 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
29d30 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
29d40 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
29d50 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
29d60 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
29d70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29d80 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
29d90 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
29da0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
29db0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
29dc0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
29dd0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
29de0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
29df0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
29e00 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
29e10 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
29e20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
29e30 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
29e40 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
29e50 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
29e60 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
29e70 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
29e80 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
29e90 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
29ea0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
29eb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
29ec0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29ed0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
29ee0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
29ef0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
29f00 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
29f10 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
29f20 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
29f30 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
29f40 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
29f50 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
29f60 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
29f70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
29f80 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
29f90 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
29fa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29fb0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
29fc0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
29fd0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
29fe0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29ff0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
2a000 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
2a010 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a020 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2a030 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2a040 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
2a050 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2a060 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2a070 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
2a080 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
2a090 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
2a0a0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
2a0b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
2a0c0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
2a0d0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
2a0e0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
2a0f0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
2a100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2a110 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
2a120 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
2a130 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2a140 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a150 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
2a160 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
2a170 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2a180 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a190 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
2a1a0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
2a1b0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
2a1c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
2a1d0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
2a1e0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
2a1f0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
2a200 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2a210 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
2a220 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
2a230 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
2a240 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2a250 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a260 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
2a270 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
2a280 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
2a290 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
2a2a0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a2b0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
2a2c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a2d0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
2a2e0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2a2f0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2a300 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2a310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
2a320 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
2a330 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
2a340 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a350 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
2a360 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2a370 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
2a380 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a390 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
2a3a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2a3b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
2a3c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a3d0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
2a3e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a3f0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2a400 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
2a410 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
2a420 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2a430 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a440 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
2a450 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2a460 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a470 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
2a480 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
2a490 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a4a0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
2a4b0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2a4c0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
2a4d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2a4e0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
2a4f0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2a500 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
2a510 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a520 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2a530 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2a540 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2a550 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
2a560 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a570 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2a580 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
2a590 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
2a5a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2a5b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a5c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2a5d0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2a5e0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2a5f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
2a600 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2a610 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2a620 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
2a630 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2a640 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a650 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a660 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
2a670 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a680 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2a690 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2a6a0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
2a6b0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
2a6c0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
2a6d0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
2a6e0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2a6f0 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2a700 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
2a710 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
2a720 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
2a730 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
2a740 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
2a750 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2a760 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2a770 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
2a780 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
2a790 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
2a7a0 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
2a7b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a7c0 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
2a7d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2a7e0 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
2a7f0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2a800 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2a810 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2a820 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73  ). ^In all cases
2a830 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
2a840 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
2a850 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2a860 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2a870 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2a880 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
2a890 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
2a8a0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
2a8b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2a8c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2a8d0 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16BE], indicatin
2a8e0 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d  g that the user-
2a8f0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74  supplied.** rout
2a900 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62  ine expects to b
2a910 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72  e passed pointer
2a920 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63  s to strings enc
2a930 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
2a940 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
2a950 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le-endian, or UT
2a960 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c  F-16 big-endian,
2a970 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e   respectively. ^
2a980 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
2a990 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
2a9a0 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
2a9b0 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  6] to indicate t
2a9c0 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a  hat the routine.
2a9d0 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ** expects point
2a9e0 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36  ers to be UTF-16
2a9f0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
2aa00 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2aa10 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67  r, or the.** arg
2aa20 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51  ument can be [SQ
2aa30 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2aa40 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68  ED] if the.** th
2aa50 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
2aa60 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
2aa70 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
2aa80 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
2aa90 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
2aaa0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2aab0 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
2aac0 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
2aad0 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
2aae0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2aaf0 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
2ab00 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69  ument.  ^If it i
2ab10 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
2ab20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
2ab30 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
2ab40 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
2ab50 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
2ab60 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
2ab70 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68  ymore)..** ^Each
2ab80 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63   time the applic
2ab90 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66  ation supplied f
2aba0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
2abb0 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64  ed, it is passed
2abc0 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74  .** as its first
2abd0 20 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70   parameter a cop
2abe0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
2abf0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
2ac00 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
2ac10 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2ac20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72  e_collation() or
2ac30 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ac40 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
2ac50 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e  *.** ^The remain
2ac60 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
2ac70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ac80 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
2ac90 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
2aca0 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
2acb0 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
2acc0 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
2acd0 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
2ace0 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
2acf0 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
2ad00 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
2ad10 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
2ad20 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2ad30 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
2ad40 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ed.  The applica
2ad50 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c  tion defined col
2ad60 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73  lation routine s
2ad70 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
2ad80 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f  negative, zero o
2ad90 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68  r positive if th
2ada0 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
2adb0 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20  s less than,.** 
2adc0 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
2add0 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
2ade0 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65  cond string. i.e
2adf0 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52  . (STRING1 - STR
2ae00 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ING2)..**.** ^Th
2ae10 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2ae20 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2ae30 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2ae40 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ae50 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
2ae60 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
2ae70 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
2ae80 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
2ae90 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
2aea0 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68   collation.  ^Th
2aeb0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2aec0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2aed0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  collation is.** 
2aee0 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73  destroyed and is
2aef0 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f   passed a copy o
2af00 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2af10 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69  ameter void* poi
2af20 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73  nter.** of the s
2af30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2af40 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  llation_v2()..**
2af50 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65   ^Collations are
2af60 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20   destroyed when 
2af70 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
2af80 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c  den by later cal
2af90 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c  ls to the.** col
2afa0 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
2afb0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
2afc0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2afd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
2afe0 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  losed.** using [
2aff0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
2b000 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2b010 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  :  [sqlite3_coll
2b020 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
2b030 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
2b040 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2b050 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b060 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b070 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ion(.  sqlite3*,
2b080 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
2b090 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
2b0a0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2b0b0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2b0c0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2b0d0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2b0e0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  st void*).);.int
2b0f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b100 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20  collation_v2(.  
2b110 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2b120 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2b130 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2b140 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
2b150 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2b160 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2b170 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2b180 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
2b190 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
2b1a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2b1b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a  te_collation16(.
2b1c0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2b1d0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65  onst void *zName
2b1e0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2b1f0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2b200 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2b210 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b220 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b230 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2b240 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
2b250 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
2b260 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
2b270 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
2b280 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
2b290 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
2b2a0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
2b2b0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
2b2c0 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
2b2d0 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
2b2e0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
2b2f0 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
2b300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2b310 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
2b320 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
2b330 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
2b340 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
2b350 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
2b360 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2b370 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
2b380 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2b390 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
2b3a0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
2b3b0 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
2b3c0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
2b3d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2b3e0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
2b3f0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
2b400 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
2b410 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b420 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
2b430 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
2b440 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
2b450 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
2b460 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2b470 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
2b480 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
2b490 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
2b4a0 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
2b4b0 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
2b4c0 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
2b4d0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
2b4e0 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
2b4f0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
2b500 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
2b510 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2b520 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
2b530 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
2b540 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2b550 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2b560 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
2b570 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2b580 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2b590 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
2b5a0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
2b5b0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
2b5c0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2b5d0 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
2b5e0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
2b5f0 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
2b600 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
2b610 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
2b620 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
2b630 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
2b640 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
2b650 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2b660 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
2b670 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
2b680 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
2b690 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
2b6a0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
2b6b0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
2b6c0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
2b6d0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2b6e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b6f0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
2b700 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2b710 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
2b720 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b730 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
2b740 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
2b750 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
2b760 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2b770 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
2b780 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2b790 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2b7a0 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
2b7b0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2b7c0 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
2b7d0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
2b7e0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2b7f0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2b800 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
2b810 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
2b820 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
2b830 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2b840 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
2b850 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
2b860 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
2b870 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
2b880 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
2b890 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
2b8a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
2b8b0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
2b8c0 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
2b8d0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
2b8e0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
2b8f0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
2b900 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
2b910 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2b920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2b930 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2b940 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2b950 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2b960 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2b970 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
2b980 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
2b990 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
2b9a0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
2b9b0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
2b9c0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
2b9d0 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
2b9e0 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
2b9f0 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
2ba00 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
2ba10 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
2ba20 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
2ba30 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2ba40 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2ba50 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2ba60 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2ba70 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2ba80 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2ba90 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
2baa0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2bab0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2bac0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
2bad0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
2bae0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
2baf0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
2bb00 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  new key */.);../
2bb10 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2bb20 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
2bb30 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 61  for a SEE databa
2bb40 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
2bb50 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
2bb60 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 69  of the SEE routi
2bb70 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a  nes will work..*
2bb80 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  /.void sqlite3_a
2bb90 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
2bba0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
2bbb0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
2bbc0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
2bbd0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
2bbe0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
2bbf0 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
2bc00 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
2bc10 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
2bc20 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
2bc30 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2bc40 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2bc50 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
2bc60 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
2bc70 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2bc80 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a  activate_cerod(.
2bc90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
2bca0 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
2bcb0 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
2bcc0 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
2bcd0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2bce0 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63  EF: Suspend Exec
2bcf0 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72  ution For A Shor
2bd00 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  t Time.**.** ^Th
2bd10 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
2bd20 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
2bd30 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
2bd40 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
2bd50 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
2bd60 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
2bd70 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2bd80 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
2bd90 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
2bda0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 65  *.** ^If the ope
2bdb0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
2bdc0 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
2bdd0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
2bde0 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
2bdf0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
2be00 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
2be10 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
2be20 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
2be30 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e 54  arest second. ^T
2be40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
2be50 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
2be60 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
2be70 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
2be80 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2be90 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
2bea0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
2beb0 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
2bec0 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
2bed0 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
2bee0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
2bef0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
2bf00 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
2bf10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
2bf20 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
2bf30 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
2bf40 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
2bf50 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
2bf60 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  Files.**.** ^(If
2bf70 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
2bf80 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
2bf90 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
2bfa0 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
2bfb0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
2bfc0 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
2bfd0 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
2bfe0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
2bff0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
2c000 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67  QLite when using
2c010 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c   a built-in [sql
2c020 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a  ite3_vfs | VFS].
2c030 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  ** will be place
2c040 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
2c050 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73  ory.)^  ^If this
2c060 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
2c070 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
2c080 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
2c090 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
2c0a0 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
2c0b0 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
2c0c0 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
2c0d0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
2c0e0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
2c0f0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2c100 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20  le in more than 
2c110 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74  one.** thread at
2c120 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20   a time.  It is 
2c130 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
2c140 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
2c150 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61  variable.** if a
2c160 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c170 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
2c180 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65  used at the same
2c190 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72   time in a separ
2c1a0 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a  ate.** thread..*
2c1b0 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  * It is intended
2c1c0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2c1d0 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a  ble be set once.
2c1e0 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72  ** as part of pr
2c1f0 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
2c200 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20  tion and before 
2c210 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72  any SQLite inter
2c220 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  face.** routines
2c230 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2c240 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  d and that this 
2c250 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20  variable remain 
2c260 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65  unchanged.** the
2c270 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  reafter..**.** ^
2c280 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  The [temp_store_
2c290 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2c2a0 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69  ] may modify thi
2c2b0 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63  s variable and c
2c2c0 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f  ause.** it to po
2c2d0 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2c2e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2c2f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e  ite3_malloc].  ^
2c300 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20  Furthermore,.** 
2c310 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2c320 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2c330 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73  ] always assumes
2c340 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67   that any string
2c350 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61  .** that this va
2c360 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f  riable points to
2c370 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f   is held in memo
2c380 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2c390 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
2c3a0 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72  lloc] and the pr
2c3b0 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74  agma may attempt
2c3c0 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65   to free that me
2c3d0 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  mory.** using [s
2c3e0 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a  qlite3_free]..**
2c3f0 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20   Hence, if this 
2c400 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69  variable is modi
2c410 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65  fied directly, e
2c420 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20  ither it should 
2c430 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20  be.** made NULL 
2c440 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  or made to point
2c450 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
2c460 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2c470 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20  3_malloc].** or 
2c480 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20  else the use of 
2c490 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  the [temp_store_
2c4a0 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
2c4b0 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  ] should be avoi
2c4c0 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ded..*/.SQLITE_E
2c4d0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
2c4e0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
2c4f0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
2c500 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75  REF: Test For Au
2c510 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a  to-Commit Mode.*
2c520 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
2c530 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a  ocommit mode}.**
2c540 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c550 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2c560 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c570 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
2c580 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67  ** zero if the g
2c590 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f  iven database co
2c5a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69  nnection is or i
2c5b0 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d  s not in autocom
2c5c0 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73  mit mode,.** res
2c5d0 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74  pectively.  ^Aut
2c5e0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2c5f0 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  on by default..*
2c600 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
2c610 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  de is disabled b
2c620 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  y a [BEGIN] stat
2c630 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  ement..** ^Autoc
2c640 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
2c650 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
2c660 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
2c670 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
2c680 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
2c690 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
2c6a0 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
2c6b0 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
2c6c0 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
2c6d0 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
2c6e0 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
2c6f0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
2c700 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
2c710 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
2c720 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
2c730 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
2c740 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
2c750 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
2c760 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
2c770 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
2c780 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
2c790 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
2c7a0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2c7b0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2c7c0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2c7d0 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
2c7e0 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
2c7f0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
2c800 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72  * If another thr
2c810 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20  ead changes the 
2c820 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75  autocommit statu
2c830 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  s of the databas
2c840 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2c850 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69  while this routi
2c860 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74  ne is running, t
2c870 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
2c880 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  alue.** is undef
2c890 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
2c8a0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2c8b0 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
2c8c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c8d0 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
2c8e0 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
2c8f0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2c900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c910 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
2c920 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2c930 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2c940 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2c950 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
2c960 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c970 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
2c980 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2c990 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
2c9a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2c9b0 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
2c9c0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2c9d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
2c9e0 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
2c9f0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
2ca00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
2ca10 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
2ca20 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
2ca30 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
2ca40 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
2ca50 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
2ca60 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
2ca70 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2ca80 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
2ca90 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2caa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2cab0 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
2cac0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2cad0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2cae0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2caf0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
2cb00 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
2cb10 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
2cb20 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
2cb30 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
2cb40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cb50 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
2cb60 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
2cb70 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
2cb80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2cb90 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
2cba0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cbb0 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
2cbc0 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
2cbd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
2cbe0 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
2cbf0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2cc00 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
2cc10 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
2cc20 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
2cc30 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
2cc40 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
2cc50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
2cc60 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
2cc70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
2cc80 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
2cc90 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
2cca0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
2ccb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
2ccc0 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
2ccd0 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
2cce0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c   pointer..*/.sql
2ccf0 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74  ite3_stmt *sqlit
2cd00 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c  e3_next_stmt(sql
2cd10 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74  ite3 *pDb, sqlit
2cd20 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2cd30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cd40 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c  : Commit And Rol
2cd50 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69  lback Notificati
2cd60 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
2cd70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cd80 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e  commit_hook() in
2cd90 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2cda0 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2cdb0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2cdc0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2cdd0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2cde0 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69   [COMMIT | commi
2cdf0 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  tted]..** ^Any c
2ce00 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2ce10 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2ce20 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  o sqlite3_commit
2ce30 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
2ce40 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2ce50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2ce60 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
2ce70 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  he sqlite3_rollb
2ce80 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ack_hook() inter
2ce90 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2cea0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
2ceb0 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
2cec0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
2ced0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52  ransaction is [R
2cee0 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64  OLLBACK | rolled
2cef0 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20   back]..** ^Any 
2cf00 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2cf10 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2cf20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  to sqlite3_rollb
2cf30 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  ack_hook().** fo
2cf40 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2cf50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2cf60 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2cf70 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d   ^The pArg argum
2cf80 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68  ent is passed th
2cf90 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c  rough to the cal
2cfa0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68  lback..** ^If th
2cfb0 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20  e callback on a 
2cfc0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63  commit hook func
2cfd0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e  tion returns non
2cfe0 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74  -zero,.** then t
2cff0 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e  he commit is con
2d000 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f  verted into a ro
2d010 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54  llback..**.** ^T
2d020 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2d030 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e  t_hook(D,C,P) an
2d040 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  d sqlite3_rollba
2d050 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  ck_hook(D,C,P) f
2d060 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75  unctions.** retu
2d070 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  rn the P argumen
2d080 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
2d090 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20  ous call of the 
2d0a0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2d0b0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
2d0c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d0d0 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
2d0e0 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
2d0f0 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e  all for each fun
2d100 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a  ction on D..**.*
2d110 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
2d120 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2d130 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2d140 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2d150 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2d160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2d170 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2d180 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
2d190 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
2d1a0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
2d1b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
2d1c0 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
2d1d0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
2d1e0 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
2d1f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2d200 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
2d210 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
2d220 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
2d230 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
2d240 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
2d250 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
2d260 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2d270 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
2d280 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
2d290 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
2d2a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
2d2b0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
2d2c0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
2d2d0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
2d2e0 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61  * ^Registering a
2d2f0 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64   NULL function d
2d300 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c  isables the call
2d310 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  back..**.** ^Whe
2d320 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  n the commit hoo
2d330 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  k callback routi
2d340 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ne returns zero,
2d350 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a   the [COMMIT].**
2d360 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c   operation is al
2d370 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75  lowed to continu
2d380 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66  e normally.  ^If
2d390 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
2d3a0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  .** returns non-
2d3b0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b  zero, then the [
2d3c0 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65  COMMIT] is conve
2d3d0 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c  rted into a [ROL
2d3e0 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20  LBACK]..** ^The 
2d3f0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
2d400 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
2d410 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
2d420 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
2d430 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
2d440 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
2d450 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
2d460 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
2d470 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
2d480 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
2d490 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
2d4a0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2d4b0 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
2d4c0 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
2d4d0 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
2d4e0 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
2d4f0 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
2d500 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
2d510 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
2d520 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
2d530 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
2d540 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ccur..** ^The ro
2d550 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
2d560 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
2d570 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
2d580 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
2d590 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
2d5a0 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61  because the data
2d5b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d5c0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  is closed..**.**
2d5d0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2d5e0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2d5f0 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ok()] interface.
2d600 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2d610 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71  3_commit_hook(sq
2d620 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
2d630 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76  oid*), void*);.v
2d640 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
2d650 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
2d660 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
2d670 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
2d680 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2d690 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
2d6a0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
2d6b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2d6c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2d6d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2d6e0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2d6f0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
2d700 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2d710 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
2d720 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
2d730 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
2d740 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2d750 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
2d760 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2d770 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
2d780 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2d790 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2d7a0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
2d7b0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
2d7c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2d7d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2d7e0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
2d7f0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2d800 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2d810 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
2d820 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
2d830 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
2d840 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2d850 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
2d860 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2d870 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
2d880 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
2d890 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
2d8a0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
2d8b0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
2d8c0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
2d8d0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
2d8e0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2d8f0 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
2d900 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
2d910 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
2d920 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
2d930 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
2d940 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
2d950 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
2d960 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
2d970 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
2d980 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
2d990 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
2d9a0 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f  tain pointers to
2d9b0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2d9c0 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20   and table name 
2d9d0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2d9e0 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20  ffected row..** 
2d9f0 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62  ^The final callb
2da00 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
2da10 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
2da20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20  the row..** ^In 
2da30 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75  the case of an u
2da40 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74  pdate, this is t
2da50 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72  he [rowid] after
2da60 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65   the update take
2da70 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  s place..**.** ^
2da80 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b  (The update hook
2da90 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2daa0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
2dab0 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
2dac0 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
2dad0 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
2dae0 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
2daf0 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  nce).)^.**.** ^I
2db00 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  n the current im
2db10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68  plementation, th
2db20 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a  e update hook.**
2db30 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2db40 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e  when duplication
2db50 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
2db60 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a  d because of an.
2db70 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  ** [ON CONFLICT 
2db80 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45  | ON CONFLICT RE
2db90 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20  PLACE] clause.  
2dba0 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61  ^Nor is the upda
2dbb0 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b  te hook.** invok
2dbc0 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65  ed when rows are
2dbd0 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74   deleted using t
2dbe0 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74  he [truncate opt
2dbf0 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  imization]..** T
2dc00 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65  he exceptions de
2dc10 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61  fined in this pa
2dc20 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68  ragraph might ch
2dc30 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
2dc40 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
2dc50 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
2dc60 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70   update hook imp
2dc70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
2dc80 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
2dc90 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
2dca0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
2dcb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
2dcc0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70  t invoked the up
2dcd0 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20  date hook.  Any 
2dce0 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
2dcf0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2dd00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2dd10 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
2dd20 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
2dd30 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
2dd40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2dd50 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
2dd60 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61  iggered the upda
2dd70 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65  te hook..** Note
2dd80 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
2dd90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2dda0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ddb0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
2ddc0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
2ddd0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
2dde0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
2ddf0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
2de00 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
2de10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
2de20 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  date_hook(D,C,P)
2de30 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74   function.** ret
2de40 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
2de50 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2de60 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e  vious call.** on
2de70 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2de80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2de90 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
2dea0 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
2deb0 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   on D..**.** See
2dec0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2ded0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2dee0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2def0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a  ollback_hook()].
2df00 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  ** interfaces..*
2df10 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
2df20 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73  update_hook(.  s
2df30 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2df40 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c  (*)(void *,int ,
2df50 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61  char const *,cha
2df60 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65  r const *,sqlite
2df70 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64  3_int64),.  void
2df80 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.);../*.** CAPI
2df90 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
2dfa0 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50  Disable Shared P
2dfb0 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45  ager Cache.** KE
2dfc0 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
2dfd0 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54  cache}.**.** ^(T
2dfe0 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
2dff0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
2e000 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
2e010 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
2e020 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
2e030 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
2e040 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
2e050 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
2e060 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
2e070 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
2e080 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
2e090 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
2e0a0 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
2e0b0 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
2e0c0 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2e0d0 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a  is false.)^.**.*
2e0e0 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67  * ^Cache sharing
2e0f0 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
2e100 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
2e110 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
2e120 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
2e130 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
2e140 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
2e150 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
2e160 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
2e170 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
2e180 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
2e190 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
2e1a0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2e1b0 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68  * ^(The cache sh
2e1c0 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
2e1d0 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
2e1e0 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
2e1f0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2e200 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
2e210 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2e220 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
2e230 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2e240 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
2e250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e260 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
2e270 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
2e280 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
2e290 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
2e2a0 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
2e2b0 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ened.)^.**.** ^(
2e2c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2e2d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2e2e0 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
2e2f0 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
2e300 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
2e310 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
2e320 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2e330 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
2e340 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65  .)^.**.** ^Share
2e350 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
2e360 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
2e370 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
2e380 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
2e390 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2e3a0 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
2e3b0 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
2e3c0 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
2e3d0 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
2e3e0 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
2e3f0 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  citly..**.** See
2e400 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20   Also:  [SQLite 
2e410 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64  Shared-Cache Mod
2e420 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e].*/.int sqlite
2e430 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
2e440 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  cache(int);../*.
2e450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74  ** CAPI3REF: Att
2e460 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61  empt To Free Hea
2e470 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e  p Memory.**.** ^
2e480 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
2e490 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74  ase_memory() int
2e4a0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2e4b0 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a  to free N bytes.
2e4c0 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  ** of heap memor
2e4d0 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e  y by deallocatin
2e4e0 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  g non-essential 
2e4f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2e500 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68  ns.** held by th
2e510 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
2e520 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65  ry.   Memory use
2e530 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62  d to cache datab
2e540 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20  ase.** pages to 
2e550 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
2e560 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  nce is an exampl
2e570 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  e of non-essenti
2e580 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73  al memory..** ^s
2e590 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2e5a0 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20  emory() returns 
2e5b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2e5c0 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65  tes actually fre
2e5d0 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67  ed,.** which mig
2e5e0 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65  ht be more or le
2e5f0 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75  ss than the amou
2e600 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
2e610 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
2e620 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
2e630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e640 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
2e650 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
2e660 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2e670 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2e680 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c  t() interface pl
2e690 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69  aces a "soft" li
2e6a0 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d  mit.** on the am
2e6b0 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
2e6c0 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
2e6d0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
2e6e0 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69  ite..** ^If an i
2e6f0 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
2e700 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
2e710 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
2e720 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  d the.** soft he
2e730 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
2e740 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2e750 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  y()] is invoked 
2e760 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  one or.** more t
2e770 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
2e780 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
2e790 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
2e7a0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
2e7b0 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20  *.** ^The limit 
2e7c0 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
2e7d0 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c   because if [sql
2e7e0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2e7f0 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74  ory()].** cannot
2e800 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
2e810 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
2e820 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
2e830 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
2e840 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
2e850 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
2e860 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
2e870 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
2e880 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  oceeds..**.** ^A
2e890 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
2e8a0 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
2e8b0 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
2e8c0 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
2e8d0 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
2e8e0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2e8f0 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
2e900 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2e910 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
2e920 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ted..** ^The def
2e930 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
2e940 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2e950 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
2e960 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73  * ^(SQLite makes
2e970 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74   a best effort t
2e980 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74  o honor the soft
2e990 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20   heap limit..** 
2e9a0 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
2e9b0 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
2e9c0 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78  t be honored, ex
2e9d0 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
2e9e0 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
2e9f0 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
2ea00 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20  cation.)^  This 
2ea10 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
2ea20 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20   is.** called a 
2ea30 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
2ea40 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
2ea50 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ly..**.** Prior 
2ea60 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
2ea70 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
2ea80 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
2ea90 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
2eaa0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
2eab0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
2eac0 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
2ead0 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
2eae0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
2eaf0 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
2eb00 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
2eb10 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
2eb20 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
2eb30 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c  ** applied to al
2eb40 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76  l threads. The v
2eb50 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
2eb60 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2eb70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
2eb80 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
2eb90 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
2eba0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
2ebb0 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a  ll threads. In.*
2ebc0 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  * version 3.5.0 
2ebd0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68  there is no mech
2ebe0 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69  anism for limiti
2ebf0 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67  ng the heap usag
2ec00 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64  e for.** individ
2ec10 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  ual threads..*/.
2ec20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
2ec30 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
2ec40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ec50 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
2ec60 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
2ec70 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
2ec80 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2ec90 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
2eca0 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
2ecb0 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
2ecc0 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
2ecd0 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
2ece0 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
2ecf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2ed00 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
2ed10 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2ed20 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
2ed30 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2ed40 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
2ed50 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
2ed60 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
2ed70 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2ed80 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
2ed90 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63  nction. ^The sec
2eda0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2edb0 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
2edc0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2edd0 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
2ede0 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20  , "temp", or an 
2edf0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2ee00 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
2ee10 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
2ee20 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49  able or NULL. ^I
2ee30 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
2ee40 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
2ee50 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
2ee60 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
2ee70 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
2ee80 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
2ee90 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
2eea0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
2eeb0 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
2eec0 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
2eed0 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  erences..**.** ^
2eee0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2eef0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2ef00 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2ef10 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
2ef20 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
2ef30 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
2ef40 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
2ef50 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
2ef60 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
2ef70 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
2ef80 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61  L..**.** ^Metada
2ef90 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ta is returned b
2efa0 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
2efb0 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
2efc0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2efd0 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  5th.** and subse
2efe0 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
2eff0 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2f000 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65  n. ^Any of these
2f010 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
2f020 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  e.** NULL, in wh
2f030 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
2f040 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
2f050 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69  nt of metadata i
2f060 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  s omitted..**.**
2f070 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a   ^(<blockquote>.
2f080 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2f090 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2f0a0 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
2f0b0 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
2f0c0 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
2f0d0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2f0e0 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
2f0f0 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
2f100 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
2f110 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
2f120 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
2f130 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
2f140 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
2f150 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
2f160 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
2f170 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
2f180 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
2f190 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
2f1a0 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
2f1b0 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2f1c0 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2f1d0 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
2f1e0 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
2f1f0 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
2f200 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
2f210 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
2f220 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
2f230 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
2f240 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2f250 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  >)^.**.** ^The m
2f260 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
2f270 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
2f280 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
2f290 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64  ned for the.** d
2f2a0 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
2f2b0 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
2f2c0 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
2f2d0 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
2f2e0 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  ext.** call to a
2f2f0 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75  ny SQLite API fu
2f300 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nction..**.** ^I
2f310 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2f320 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
2f330 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72  y a view, an [er
2f340 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2f350 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  urned..**.** ^If
2f360 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
2f370 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
2f380 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
2f390 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
2f3a0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2f3b0 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
2f3c0 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
2f3d0 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
2f3e0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2f3f0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2f400 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
2f410 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
2f420 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  mn. ^(If there i
2f430 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
2f440 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
2f450 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
2f460 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
2f470 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
2f480 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
2f490 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
2f4a0 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
2f4b0 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
2f4c0 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
2f4d0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
2f4e0 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
2f4f0 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
2f500 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
2f510 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
2f520 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
2f530 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  re>)^.**.** ^(Th
2f540 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
2f550 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
2f560 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
2f570 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
2f580 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
2f590 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
2f5a0 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
2f5b0 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
2f5c0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
2f5d0 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
2f5e0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
2f5f0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
2f600 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
2f610 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
2f620 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f630 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
2f640 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
2f650 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
2f660 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  )^.**.** ^This A
2f670 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
2f680 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2f690 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2f6a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2f6b0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2f6c0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2f6d0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2f6e0 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
2f6f0 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
2f700 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
2f710 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2f720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f730 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
2f740 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2f750 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
2f760 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2f770 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
2f780 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2f790 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
2f7a0 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
2f7b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2f7c0 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
2f7d0 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
2f7e0 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
2f7f0 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
2f800 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
2f810 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
2f820 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
2f830 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
2f840 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
2f850 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
2f860 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
2f870 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
2f880 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
2f890 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
2f8a0 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
2f8b0 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
2f8c0 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
2f8d0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
2f8e0 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
2f8f0 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
2f900 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
2f910 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
2f920 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
2f930 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
2f940 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
2f950 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
2f960 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
2f970 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
2f980 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
2f990 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
2f9a0 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
2f9b0 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
2f9c0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2f9d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2f9e0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
2f9f0 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
2fa00 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
2fa10 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
2fa20 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
2fa30 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
2fa40 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
2fa50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
2fa60 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
2fa70 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
2fa80 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
2fa90 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
2faa0 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
2fab0 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
2fac0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
2fad0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
2fae0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2faf0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
2fb00 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
2fb10 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
2fb20 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
2fb30 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
2fb40 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
2fb50 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
2fb60 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
2fb70 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
2fb80 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
2fb90 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
2fba0 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
2fbb0 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
2fbc0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
2fbd0 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
2fbe0 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
2fbf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2fc00 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
2fc10 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
2fc20 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
2fc30 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
2fc40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
2fc50 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
2fc60 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
2fc70 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
2fc80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
2fc90 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
2fca0 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
2fcb0 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
2fcc0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2fcd0 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
2fce0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
2fcf0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
2fd00 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
2fd10 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
2fd20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
2fd30 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
2fd40 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2fd50 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
2fd60 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
2fd70 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
2fd80 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
2fd90 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
2fda0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
2fdb0 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
2fdc0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
2fdd0 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
2fde0 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
2fdf0 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
2fe00 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
2fe10 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
2fe20 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
2fe30 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
2fe40 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
2fe50 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
2fe60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2fe70 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
2fe80 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
2fe90 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20  ng.**.** ^So as 
2fea0 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
2feb0 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
2fec0 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
2fed0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
2fee0 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
2fef0 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
2ff00 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
2ff10 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
2ff20 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
2ff30 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
2ff40 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
2ff50 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
2ff60 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
2ff70 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2ff80 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
2ff90 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
2ffa0 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
2ffb0 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
2ffc0 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
2ffd0 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
2ffe0 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
2fff0 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c   #1863..** ^Call
30000 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
30010 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
30020 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
30030 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f  h onoff==1.** to
30040 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
30050 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
30060 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
30070 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
30080 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
30090 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
300a0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
300b0 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
300c0 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
300d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
300e0 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
300f0 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
30100 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  ns.**.** ^This A
30110 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
30120 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
30130 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
30140 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
30150 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
30160 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
30170 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
30180 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
30190 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61  to all new [data
301a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
301b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ]..**.** ^(This 
301c0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
301d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
301e0 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20  extension entry 
301f0 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61  point.** in an a
30200 72 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74  rray that is obt
30210 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
30220 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
30230 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  That memory.** i
30240 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  s deallocated by
30250 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
30260 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
30270 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ].)^.**.** ^This
30280 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
30290 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  ers an extension
302a0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61   entry point tha
302b0 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  t is.** automati
302c0 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68  cally invoked wh
302d0 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61  enever a new [da
302e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
302f0 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20  n].** is opened 
30300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
30310 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
30320 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f  _open16()],.** o
30330 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
30340 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69  v2()]..** ^Dupli
30350 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
30360 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
30370 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
30380 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  tine.** multiple
30390 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
303a0 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69  same extension i
303b0 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e  s harmless..** ^
303c0 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  Automatic extens
303d0 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73  ions apply acros
303e0 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  s all threads..*
303f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
30400 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
30410 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  d (*xEntryPoint)
30420 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void));../*.** 
30430 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
30440 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
30450 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
30460 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
30470 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
30480 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
30490 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a  ered automatic.*
304a0 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74  * extensions. It
304b0 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
304c0 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a  ct of all prior.
304d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  ** [sqlite3_auto
304e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61  _extension()] ca
304f0 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lls.)^.**.** ^Th
30500 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
30510 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65  bles automatic e
30520 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c  xtensions in all
30530 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69   threads..*/.voi
30540 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
30550 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
30560 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  oid);../*.** The
30570 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
30580 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
30590 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
305a0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
305b0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
305c0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
305d0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
305e0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
305f0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
30600 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
30610 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
30620 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
30630 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
30640 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
30650 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
30660 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
30670 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
30680 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
30690 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
306a0 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
306b0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
306c0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
306d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
306e0 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
306f0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
30700 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
30710 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
30720 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
30730 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
30740 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
30750 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
30760 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
30770 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
30780 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
30790 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
307a0 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
307b0 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
307c0 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
307d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
307e0 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
307f0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
30800 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
30810 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
30820 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a  le module}.**.**
30830 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
30840 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
30850 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74  d a a "virtual t
30860 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a  able module", .*
30870 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d  * defines the im
30880 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
30890 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
308a0 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74  s].  .** This st
308b0 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
308c0 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
308d0 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
308e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74  e..**.** ^A virt
308f0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
30900 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66   is created by f
30910 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73  illing in a pers
30920 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e  istent.** instan
30930 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
30940 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
30950 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30960 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74  at instance.** t
30970 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
30980 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b  e_module()] or [
30990 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
309a0 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  odule_v2()]..** 
309b0 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f  ^The registratio
309c0 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20  n remains valid 
309d0 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c  until it is repl
309e0 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72  aced by a differ
309f0 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72  ent.** module or
30a00 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61   until the [data
30a10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30a20 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f   closes.  The co
30a30 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73  ntent.** of this
30a40 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
30a50 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65  not change while
30a60 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65   it is registere
30a70 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61  d with.** any da
30a80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30a90 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  n..*/.struct sql
30aa0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
30ab0 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
30ac0 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
30ad0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
30ae0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
30af0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
30b00 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
30b10 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
30b20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
30b30 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
30b40 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
30b50 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
30b60 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
30b70 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
30b80 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
30b90 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
30ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
30bb0 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
30bc0 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
30bd0 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
30be0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30bf0 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
30c00 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
30c10 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
30c20 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30c30 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
30c40 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
30c50 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
30c60 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
30c70 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30c80 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
30c90 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
30ca0 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
30cb0 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
30cc0 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
30cd0 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
30ce0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
30cf0 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
30d00 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
30d10 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30d20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
30d30 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
30d40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
30d50 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
30d60 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
30d70 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(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 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
30da0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30db0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
30dc0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
30dd0 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
30de0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
30df0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
30e00 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
30e10 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
30e20 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
30e30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
30e40 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
30e50 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
30e60 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
30e70 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30e80 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(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 43 6f 6d 6d 69 74 29    int (*xCommit)
30eb0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30ec0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
30ed0 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
30ee0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
30ef0 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
30f00 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
30f10 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
30f20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
30f30 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
30f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30f50 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
30f60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30f70 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
30f80 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
30f90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
30fa0 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69  id **ppArg);.  i
30fb0 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
30fc0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
30fd0 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
30fe0 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
30ff0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
31000 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
31010 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   Information.** 
31020 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
31030 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a  3_index_info.**.
31040 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
31050 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
31060 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73  ure and its subs
31070 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65  tructures is use
31080 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66  d to.** pass inf
31090 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e  ormation into an
310a0 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65  d receive the re
310b0 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42  ply from the [xB
310c0 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74  estIndex].** met
310d0 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61  hod of a [virtua
310e0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
310f0 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64    The fields und
31100 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72  er **Inputs** ar
31110 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20  e the.** inputs 
31120 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e  to xBestIndex an
31130 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e  d are read-only.
31140 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73    xBestIndex ins
31150 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75  erts its.** resu
31160 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f  lts into the **O
31170 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e  utputs** fields.
31180 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f  .**.** ^(The aCo
31190 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
311a0 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63   records WHERE c
311b0 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74  lause constraint
311c0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a  s of the form:.*
311d0 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e  *.** <pre>column
311e0 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a   OP expr</pre>.*
311f0 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73  *.** where OP is
31200 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c   =, &lt;, &lt;=,
31210 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e   &gt;, or &gt;=.
31220 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69 63  )^  ^(The partic
31230 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73  ular operator is
31240 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43  .** stored in aC
31250 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29  onstraint[].op.)
31260 5e 20 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f  ^  ^(The index o
31270 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
31280 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f  stored in.** aCo
31290 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75  nstraint[].iColu
312a0 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72  mn.)^  ^(aConstr
312b0 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73  aint[].usable is
312c0 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20   TRUE if the.** 
312d0 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68  expr on the righ
312e0 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20  t-hand side can 
312f0 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e  be evaluated (an
31300 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74  d thus the const
31310 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62  raint.** is usab
31320 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66  le) and false if
31330 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a   it cannot.)^.**
31340 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a  .** ^The optimiz
31350 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  er automatically
31360 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f   inverts terms o
31370 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72  f the form "expr
31380 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61   OP column".** a
31390 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73  nd makes other s
313a0 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74  implifications t
313b0 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  o the WHERE clau
313c0 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74  se in an attempt
313d0 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61   to.** get as ma
313e0 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ny WHERE clause 
313f0 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66  terms into the f
31400 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  orm shown above 
31410 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20  as possible..** 
31420 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^The aConstraint
31430 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65  [] array only re
31440 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75  ports WHERE clau
31450 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72  se terms that ar
31460 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f  e.** relevant to
31470 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
31480 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65  virtual table be
31490 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a  ing queried..**.
314a0 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20  ** ^Information 
314b0 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20  about the ORDER 
314c0 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f  BY clause is sto
314d0 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b  red in aOrderBy[
314e0 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d  ]..** ^Each term
314f0 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63   of aOrderBy rec
31500 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66  ords a column of
31510 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
31520 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ause..**.** The 
31530 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74  [xBestIndex] met
31540 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43  hod must fill aC
31550 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
31560 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f   with informatio
31570 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20  n.** about what 
31580 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61  parameters to pa
31590 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20  ss to xFilter.  
315a0 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20  ^If argvIndex>0 
315b0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68  then.** the righ
315c0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74  t-hand side of t
315d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
315e0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69   aConstraint[] i
315f0 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61  s evaluated.** a
31600 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61  nd becomes the a
31610 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72  rgvIndex-th entr
31620 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66  y in argv.  ^(If
31630 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
31640 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74  e[].omit.** is t
31650 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  rue, then the co
31660 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75  nstraint is assu
31670 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20  med to be fully 
31680 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a  handled by the.*
31690 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * virtual table 
316a0 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b  and is not check
316b0 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69  ed again by SQLi
316c0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te.)^.**.** ^The
316d0 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50   idxNum and idxP
316e0 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65  tr values are re
316f0 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65  corded and passe
31700 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78  d into the.** [x
31710 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a  Filter] method..
31720 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65  ** ^[sqlite3_fre
31730 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  e()] is used to 
31740 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61  free idxPtr if a
31750 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65  nd only if.** ne
31760 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69  edToFreeIdxPtr i
31770 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s true..**.** ^T
31780 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d  he orderByConsum
31790 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75  ed means that ou
317a0 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74  tput from [xFilt
317b0 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c  er]/[xNext] will
317c0 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65   occur in.** the
317d0 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74   correct order t
317e0 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52  o satisfy the OR
317f0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f  DER BY clause so
31800 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74   that no separat
31810 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65  e.** sorting ste
31820 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  p is required..*
31830 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61  *.** ^The estima
31840 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73  tedCost value is
31850 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
31860 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e  the cost of doin
31870 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75  g the.** particu
31880 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66  lar lookup.  A f
31890 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61  ull scan of a ta
318a0 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69  ble with N entri
318b0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a  es should have.*
318c0 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20  * a cost of N.  
318d0 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20  A binary search 
318e0 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20  of a table of N 
318f0 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
31900 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66  ave a.** cost of
31910 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c   approximately l
31920 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74  og(N)..*/.struct
31930 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
31940 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74  nfo {.  /* Input
31950 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73  s */.  int nCons
31960 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
31970 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65    /* Number of e
31980 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74  ntries in aConst
31990 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63  raint */.  struc
319a0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
319b0 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20  constraint {.   
319c0 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
319d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
319e0 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61  olumn on left-ha
319f0 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74  nd side of const
31a00 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e  raint */.     un
31a10 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20  signed char op; 
31a20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74          /* Const
31a30 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a  raint operator *
31a40 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
31a50 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20  char usable;    
31a60 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73   /* True if this
31a70 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75   constraint is u
31a80 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e  sable */.     in
31a90 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20  t iTermOffset;  
31aa0 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20          /* Used 
31ab0 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65  internally - xBe
31ac0 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69  stIndex should i
31ad0 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43  gnore */.  } *aC
31ae0 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
31af0 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f        /* Table o
31b00 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  f WHERE clause c
31b10 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20  onstraints */.  
31b20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20  int nOrderBy;   
31b30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
31b40 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
31b50 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
31b60 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74  ause */.  struct
31b70 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f   sqlite3_index_o
31b80 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e  rderby {.     in
31b90 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
31ba0 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
31bb0 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20  n number */.    
31bc0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64   unsigned char d
31bd0 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  esc;       /* Tr
31be0 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61  ue for DESC.  Fa
31bf0 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a  lse for ASC. */.
31c00 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20    } *aOrderBy;  
31c10 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31c20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  The ORDER BY cla
31c30 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70  use */.  /* Outp
31c40 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  uts */.  struct 
31c50 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f  sqlite3_index_co
31c60 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b  nstraint_usage {
31c70 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64  .    int argvInd
31c80 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ex;           /*
31c90 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69   if >0, constrai
31ca0 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72  nt is part of ar
31cb0 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f  gv to xFilter */
31cc0 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68  .    unsigned ch
31cd0 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a  ar omit;      /*
31ce0 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74   Do not code a t
31cf0 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e  est for this con
31d00 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a  straint */.  } *
31d10 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
31d20 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20  ;.  int idxNum; 
31d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31d40 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f  * Number used to
31d50 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e   identify the in
31d60 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69  dex */.  char *i
31d70 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20  dxStr;          
31d80 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70      /* String, p
31d90 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64  ossibly obtained
31da0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
31db0 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65  lloc */.  int ne
31dc0 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20  edToFreeIdxStr; 
31dd0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78       /* Free idx
31de0 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65  Str using sqlite
31df0 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65  3_free() if true
31e00 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42   */.  int orderB
31e10 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20  yConsumed;      
31e20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70   /* True if outp
31e30 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72  ut is already or
31e40 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c  dered */.  doubl
31e50 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b  e estimatedCost;
31e60 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74        /* Estimat
31e70 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67  ed cost of using
31e80 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d   this index */.}
31e90 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
31ea0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
31eb0 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e  T_EQ    2.#defin
31ec0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
31ed0 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20  ONSTRAINT_GT    
31ee0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
31ef0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
31f00 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e  T_LE    8.#defin
31f10 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
31f20 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20  ONSTRAINT_LT    
31f30 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
31f40 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
31f50 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66  NT_GE    32.#def
31f60 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
31f70 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43  _CONSTRAINT_MATC
31f80 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  H 64../*.** CAPI
31f90 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
31fa0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
31fb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
31fc0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
31fd0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  nes are used to 
31fe0 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b  register a new [
31ff0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
32000 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  dule] name..** ^
32010 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73  Module names mus
32020 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  t be registered 
32030 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69  before.** creati
32040 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  ng a new [virtua
32050 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74  l table] using t
32060 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65  he module and be
32070 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20  fore using a.** 
32080 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72  preexisting [vir
32090 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20  tual table] for 
320a0 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a  the module..**.*
320b0 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61  * ^The module na
320c0 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64  me is registered
320d0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
320e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
320f0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
32100 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
32110 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  r.  ^The name of
32120 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67   the module is g
32130 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20  iven by the .** 
32140 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
32150 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
32160 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
32170 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69  nter to.** the i
32180 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32190 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
321a0 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e  ble module].   ^
321b0 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61  The fourth.** pa
321c0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
321d0 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64  bitrary client d
321e0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
321f0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
32200 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b  gh.** into the [
32210 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43  xCreate] and [xC
32220 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20  onnect] methods 
32230 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  of the virtual t
32240 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77  able module.** w
32250 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61  hen a new virtua
32260 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65  l table is be be
32270 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72  ing created or r
32280 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a  einitialized..**
32290 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
322a0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
322b0 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61  2() interface ha
322c0 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65  s a fifth parame
322d0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
322e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64  a pointer to a d
322f0 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
32300 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20  e pClientData.  
32310 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20  ^SQLite will.** 
32320 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
32330 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28  uctor function (
32340 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c  if it is not NUL
32350 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a  L) when SQLite.*
32360 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  * no longer need
32370 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  s the pClientDat
32380 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  a pointer.  ^The
32390 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
323a0 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65  module().** inte
323b0 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
323c0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
323d0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
323e0 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a  ) with a NULL.**
323f0 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a   destructor..*/.
32400 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32410 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
32420 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
32430 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
32440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
32450 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
32460 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
32470 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
32480 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
32490 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
324a0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
324b0 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65  dule *p,   /* Me
324c0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
324d0 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
324e0 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20  pClientData     
324f0 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
32500 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
32510 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69  xConnect */.);.i
32520 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
32530 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
32540 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
32550 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
32560 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
32570 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
32580 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
32590 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
325a0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
325b0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
325c0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
325d0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
325e0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
325f0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
32600 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20   *pClientData,  
32610 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
32620 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
32630 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
32640 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
32650 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
32660 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
32670 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
32680 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32690 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
326a0 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  stance Object.**
326b0 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
326c0 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76  e3_vtab.**.** Ev
326d0 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ery [virtual tab
326e0 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65  le module] imple
326f0 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
32700 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20   subclass.** of 
32710 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64  this object to d
32720 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63  escribe a partic
32730 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  ular instance.**
32740 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
32750 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73   table].  Each s
32760 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20  ubclass will.** 
32770 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74  be tailored to t
32780 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
32790 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  s of the module 
327a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
327b0 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f  ** The purpose o
327c0 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73  f this superclas
327d0 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63  s is to define c
327e0 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68  ertain fields th
327f0 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e  at are.** common
32800 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69   to all module i
32810 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
32820 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74  **.** ^Virtual t
32830 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
32840 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
32850 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
32860 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
32870 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
32880 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
32890 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54  ] to zErrMsg.  T
328a0 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  he method should
328b0 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68  .** take care th
328c0 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72  at any prior str
328d0 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20  ing is freed by 
328e0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
328f0 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72  e3_free()].** pr
32900 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
32910 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
32920 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65   zErrMsg.  ^Afte
32930 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
32940 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65  age.** is delive
32950 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c  red up to the cl
32960 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ient application
32970 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  , the string wil
32980 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
32990 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73  ly.** freed by s
329a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e  qlite3_free() an
329b0 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  d the zErrMsg fi
329c0 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f  eld will be zero
329d0 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ed..*/.struct sq
329e0 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
329f0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
32a00 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
32a10 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
32a20 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
32a30 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
32a40 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
32a50 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c           /* NO L
32a60 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20  ONGER USED */.  
32a70 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20  char *zErrMsg;  
32a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32a90 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  /* Error message
32aa0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
32ab0 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20  rintf() */.  /* 
32ac0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
32ad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
32ae0 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
32af0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
32b00 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
32b10 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
32b20 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f  l Table Cursor O
32b30 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
32b40 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  S: sqlite3_vtab_
32b50 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20  cursor {virtual 
32b60 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a  table cursor}.**
32b70 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
32b80 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
32b90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32ba0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
32bb0 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  of the.** follow
32bc0 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
32bd0 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
32be0 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
32bf0 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61  o the.** [virtua
32c00 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65  l table] and are
32c10 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
32c20 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
32c30 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
32c40 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
32c50 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
32c60 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f  qlite3_module.xO
32c70 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74  pen | xOpen] met
32c80 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
32c90 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f  e and are destro
32ca0 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73  yed.** by the [s
32cb0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43  qlite3_module.xC
32cc0 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d  lose | xClose] m
32cd0 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20  ethod.  Cursors 
32ce0 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74  are used.** by t
32cf0 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78  he [xFilter], [x
32d00 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b  Next], [xEof], [
32d10 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78  xColumn], and [x
32d20 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a  Rowid] methods.*
32d30 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  * of the module.
32d40 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
32d50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
32d60 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
32d70 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
32d80 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
32d90 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
32da0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
32db0 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
32dc0 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
32dd0 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
32de0 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
32df0 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
32e00 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
32e10 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
32e20 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
32e30 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
32e40 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
32e50 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
32e60 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
32e70 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
32e80 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
32e90 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
32ea0 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
32eb0 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
32ec0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32ed0 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
32ee0 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
32ef0 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e  al Table.**.** ^
32f00 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  The [xCreate] an
32f10 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
32f20 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69  hods of a.** [vi
32f30 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
32f40 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e  le] call this in
32f50 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65  terface.** to de
32f60 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
32f70 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
32f80 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
32f90 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
32fa0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
32fb0 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
32fc0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
32fd0 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73  3_declare_vtab(s
32fe0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
32ff0 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a  har *zSQL);../*.
33000 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65  ** CAPI3REF: Ove
33010 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e  rload A Function
33020 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54   For A Virtual T
33030 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72  able.**.** ^(Vir
33040 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
33050 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
33060 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
33070 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
33080 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78  .** using the [x
33090 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65  FindFunction] me
330a0 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72  thod of the [vir
330b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
330c0 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f  e].  .** But glo
330d0 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  bal versions of 
330e0 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  those functions.
330f0 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e  ** must exist in
33100 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65   order to be ove
33110 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  rloaded.)^.**.**
33120 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65   ^(This API make
33130 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
33140 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
33150 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
33160 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
33170 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
33180 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
33190 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
331a0 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
331b0 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
331c0 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
331d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
331e0 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d  ated.)^  ^The im
331f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
33200 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
33210 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
33220 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
33230 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
33240 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
33250 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
33260 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
33270 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
33280 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
33290 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f   to be a placeho
332a0 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
332b0 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
332c0 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69  aded.** by a [vi
332d0 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f  rtual table]..*/
332e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65  .int sqlite3_ove
332f0 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73  rload_function(s
33300 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
33310 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20  har *zFuncName, 
33320 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a  int nArg);../*.*
33330 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
33340 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
33350 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64  able mechanism d
33360 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61  efined above (ba
33370 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f  ck up.** to a co
33380 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79  mment remarkably
33390 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73   similar to this
333a0 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74   one) is current
333b0 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
333c0 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
333d0 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
333e0 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
333f0 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
33400 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
33410 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
33420 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
33430 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
33440 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
33450 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
33460 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
33470 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
33480 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
33490 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
334a0 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
334b0 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
334c0 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
334d0 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
334e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
334f0 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f  A Handle To An O
33500 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57  pen BLOB.** KEYW
33510 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64  ORDS: {BLOB hand
33520 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65  le} {BLOB handle
33530 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
33540 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
33550 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
33560 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77  n open BLOB on w
33570 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
33580 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
33590 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
335a0 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  O] can be perfor
335b0 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73  med..** ^Objects
335c0 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
335d0 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  e created by [sq
335e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
335f0 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f  )].** and destro
33600 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
33610 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
33620 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
33630 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
33640 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
33650 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63  rite()] interfac
33660 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  es.** can be use
33670 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  d to read or wri
33680 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74  te small subsect
33690 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ions of the BLOB
336a0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
336b0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
336c0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
336d0 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
336e0 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73  he BLOB in bytes
336f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
33700 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  uct sqlite3_blob
33710 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a   sqlite3_blob;..
33720 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33730 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20  Open A BLOB For 
33740 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a  Incremental I/O.
33750 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
33760 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20  erfaces opens a 
33770 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68  [BLOB handle | h
33780 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c  andle] to the BL
33790 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e  OB located.** in
337a0 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d   row iRow, colum
337b0 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65  n zColumn, table
337c0 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62   zTable in datab
337d0 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f  ase zDb;.** in o
337e0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
337f0 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77  same BLOB that w
33800 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64  ould be selected
33810 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
33820 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
33830 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
33840 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f  zTable WHERE [ro
33850 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20  wid] = iRow;.** 
33860 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
33870 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  If the flags par
33880 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65  ameter is non-ze
33890 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f  ro, then the BLO
338a0 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
338b0 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74  read.** and writ
338c0 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74  e access. ^If it
338d0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c   is zero, the BL
338e0 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
338f0 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a   read access..**
33900 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73   ^It is not poss
33910 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
33920 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
33930 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f  rt of an index o
33940 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65  r primary .** ke
33950 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e  y for writing. ^
33960 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  If [foreign key 
33970 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65  constraints] are
33980 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20   enabled, it is 
33990 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
339a0 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
339b0 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
339c0 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20  f a [child key] 
339d0 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a  for writing..**.
339e0 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
339f0 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
33a00 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e  is not the filen
33a10 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ame that contain
33a20 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
33a30 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65  e but rather the
33a40 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f   symbolic name o
33a50 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  f the database t
33a60 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61  hat.** appears a
33a70 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77  fter the AS keyw
33a80 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ord when the dat
33a90 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74  abase is connect
33aa0 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48  ed using [ATTACH
33ab0 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d  ]..** ^For the m
33ac0 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
33ad0 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  e, the database 
33ae0 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a  name is "main"..
33af0 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62  ** ^For TEMP tab
33b00 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73  les, the databas
33b10 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22  e name is "temp"
33b20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
33b30 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
33b40 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
33b50 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20  d the new [BLOB 
33b60 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74  handle] is writt
33b70 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62  en.** to *ppBlob
33b80 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  . Otherwise an [
33b90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
33ba0 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42  eturned and *ppB
33bb0 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  lob is set.** to
33bc0 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74   be a null point
33bd0 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66  er.)^.** ^This f
33be0 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65  unction sets the
33bf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33c00 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64  ction] error cod
33c10 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a  e and message.**
33c20 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
33c30 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
33c40 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33c50 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72  _errmsg()] and r
33c60 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69  elated.** functi
33c70 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20  ons. ^Note that 
33c80 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69  the *ppBlob vari
33c90 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69  able is always i
33ca0 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a  nitialized in a.
33cb0 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65  ** way that make
33cc0 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76  s it safe to inv
33cd0 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  oke [sqlite3_blo
33ce0 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70  b_close()] on *p
33cf0 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c  pBlob.** regardl
33d00 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
33d10 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ss or failure of
33d20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a   this routine..*
33d30 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f  *.** ^(If the ro
33d40 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61  w that a BLOB ha
33d50 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  ndle points to i
33d60 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e  s modified by an
33d70 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44  .** [UPDATE], [D
33d80 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f  ELETE], or by [O
33d90 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65  N CONFLICT] side
33da0 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e  -effects.** then
33db0 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
33dc0 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65   is marked as "e
33dd0 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73  xpired"..** This
33de0 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20   is true if any 
33df0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f  column of the ro
33e00 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76  w is changed, ev
33e10 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f  en a column.** o
33e20 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e  ther than the on
33e30 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  e the BLOB handl
33e40 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a  e is open on.)^.
33e50 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71  ** ^Calls to [sq
33e60 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
33e70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
33e80 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f  blob_write()] fo
33e90 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42  r.** a expired B
33ea0 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20  LOB handle fail 
33eb0 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63  with an return c
33ec0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
33ed0 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e  BORT]..** ^(Chan
33ee0 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  ges written into
33ef0 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f   a BLOB prior to
33f00 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69   the BLOB expiri
33f10 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f  ng are not.** ro
33f20 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
33f30 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74   expiration of t
33f40 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63  he BLOB.  Such c
33f50 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e  hanges will even
33f60 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74  tually.** commit
33f70 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74   if the transact
33f80 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ion continues to
33f90 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a   completion.)^.*
33fa0 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73  *.** ^Use the [s
33fb0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
33fc0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  s()] interface t
33fd0 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
33fe0 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  size of.** the o
33ff0 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68  pened blob.  ^Th
34000 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
34010 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e   may not be chan
34020 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69  ged by this.** i
34030 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74  nterface.  Use t
34040 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20  he [UPDATE] SQL 
34050 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67  command to chang
34060 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a  e the size of a.
34070 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e  ** blob..**.** ^
34080 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
34090 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e  d_zeroblob()] an
340a0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
340b0 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e  t_zeroblob()] in
340c0 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20  terfaces.** and 
340d0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65  the built-in [ze
340e0 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63  roblob] SQL func
340f0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
34100 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a  , if desired,.**
34110 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d   to create an em
34120 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64  pty, zero-filled
34130 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74   blob in which t
34140 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
34150 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e  using.** this in
34160 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
34170 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72  o avoid a resour
34180 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f  ce leak, every o
34190 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
341a0 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61  ] should eventua
341b0 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73  lly.** be releas
341c0 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
341d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
341e0 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ose()]..*/.int s
341f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
34200 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
34210 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
34220 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34230 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
34240 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
34250 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
34260 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
34270 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
34280 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
34290 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
342a0 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65  se A BLOB Handle
342b0 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20 61  .**.** ^Closes a
342c0 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  n open [BLOB han
342d0 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f  dle]..**.** ^Clo
342e0 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61 6c  sing a BLOB shal
342f0 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72 72  l cause the curr
34300 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ent transaction 
34310 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20  to commit.** if 
34320 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74 68  there are no oth
34330 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e  er BLOBs, no pen
34340 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73 74  ding prepared st
34350 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68  atements, and th
34360 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
34370 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b  nnection is in [
34380 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d  autocommit mode]
34390 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72 69  ..** ^If any wri
343a0 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74 6f  tes were made to
343b0 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79 20   the BLOB, they 
343c0 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69 6e  might be held in
343d0 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c 20   cache.** until 
343e0 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61 74  the close operat
343f0 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c 6c  ion if they will
34400 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c   fit..**.** ^(Cl
34410 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20 6f  osing the BLOB o
34420 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65 20  ften forces the 
34430 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20 74  changes.** out t
34440 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69 66  o disk and so if
34450 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73 20   any I/O errors 
34460 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c 6c  occur, they will
34470 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a 2a   likely occur.**
34480 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
34490 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  n the BLOB is cl
344a0 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f 72  osed.  Any error
344b0 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75 72  s that occur dur
344c0 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20 61  ing.** closing a
344d0 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20 61  re reported as a
344e0 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
344f0 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20   value.)^.**.** 
34500 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c  ^(The BLOB is cl
34510 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e  osed uncondition
34520 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74  ally.  Even if t
34530 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
34540 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  rns.** an error 
34550 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69  code, the BLOB i
34560 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 29  s still closed.)
34570 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ^.**.** ^Calling
34580 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
34590 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  th a null pointe
345a0 72 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c 64  r (such as would
345b0 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   be returned.** 
345c0 62 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c 6c  by a failed call
345d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
345e0 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61 20  b_open()]) is a 
345f0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
34600 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
34610 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  lob_close(sqlite
34620 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a  3_blob *);../*.*
34630 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 75  * CAPI3REF: Retu
34640 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20 41  rn The Size Of A
34650 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a  n Open BLOB.**.*
34660 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20 73  * ^Returns the s
34670 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66 20  ize in bytes of 
34680 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73 69  the BLOB accessi
34690 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a 20  ble via the .** 
346a0 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70 65  successfully ope
346b0 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  ned [BLOB handle
346c0 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72  ] in its only ar
346d0 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a 2a  gument.  ^The.**
346e0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c 6f   incremental blo
346f0 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20 63  b I/O routines c
34700 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72 20  an only read or 
34710 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 69 73  overwriting exis
34720 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e  ting.** blob con
34730 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e 6f  tent; they canno
34740 74 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a  t change the siz
34750 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a  e of a blob..**.
34760 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34770 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
34780 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
34790 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
347a0 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
347b0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
347c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
347d0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
347e0 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
347f0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
34800 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
34810 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
34820 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
34830 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
34840 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
34850 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
34860 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
34870 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
34880 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34890 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69 74  blob_bytes(sqlit
348a0 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a  e3_blob *);../*.
348b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 61  ** CAPI3REF: Rea
348c0 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42 4c  d Data From A BL
348d0 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  OB Incrementally
348e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
348f0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  nction is used t
34900 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f 6d  o read data from
34910 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
34920 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a  andle] into a.**
34930 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64   caller-supplied
34940 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65 73   buffer. N bytes
34950 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f 70   of data are cop
34960 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72 20  ied into buffer 
34970 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f 70  Z.** from the op
34980 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e  en BLOB, startin
34990 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66  g at offset iOff
349a0 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  set.)^.**.** ^If
349b0 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20   offset iOffset 
349c0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62  is less than N b
349d0 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e  ytes from the en
349e0 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a  d of the BLOB,.*
349f0 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
34a00 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
34a10 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
34a20 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66 66  .  ^If N or iOff
34a30 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  set is.** less t
34a40 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54  han zero, [SQLIT
34a50 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
34a60 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
34a70 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54 68   is read..** ^Th
34a80 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c  e size of the bl
34a90 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68  ob (and hence th
34aa0 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20  e maximum value 
34ab0 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a  of N+iOffset).**
34ac0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
34ad0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ed using the [sq
34ae0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
34af0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
34b00 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74  *.** ^An attempt
34b10 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e   to read from an
34b20 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68   expired [BLOB h
34b30 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74  andle] fails wit
34b40 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f  h an.** error co
34b50 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
34b60 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ORT]..**.** ^(On
34b70 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
34b80 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72 65  3_blob_read() re
34b90 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e  turns SQLITE_OK.
34ba0 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
34bb0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
34bc0 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
34bd0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
34be0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
34bf0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
34c00 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
34c10 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
34c20 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
34c30 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
34c40 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
34c50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
34c60 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
34c70 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
34c80 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
34c90 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
34ca0 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
34cb0 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
34cc0 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
34cd0 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
34ce0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
34cf0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
34d00 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
34d10 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
34d20 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
34d30 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
34d40 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73  ite3_blob_read(s
34d50 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76  qlite3_blob *, v
34d60 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69  oid *Z, int N, i
34d70 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
34d80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72  .** CAPI3REF: Wr
34d90 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20  ite Data Into A 
34da0 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
34db0 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ly.**.** ^This f
34dc0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
34dd0 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69 6e  to write data in
34de0 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  to an open [BLOB
34df0 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61 0a   handle] from a.
34e00 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
34e10 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62 79  ed buffer. ^N by
34e20 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
34e30 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20  copied from the 
34e40 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f  buffer Z.** into
34e50 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
34e60 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
34e70 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
34e80 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42 20  * ^If the [BLOB 
34e90 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61  handle] passed a
34ea0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
34eb0 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65  ment was not ope
34ec0 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69  ned for.** writi
34ed0 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61  ng (the flags pa
34ee0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
34ef0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
34f00 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74   was zero),.** t
34f10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
34f20 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  urns [SQLITE_REA
34f30 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  DONLY]..**.** ^T
34f40 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
34f50 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65   only modify the
34f60 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65   contents of the
34f70 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20   BLOB; it is.** 
34f80 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
34f90 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69 7a  increase the siz
34fa0 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e  e of a BLOB usin
34fb0 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 5e  g this API..** ^
34fc0 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
34fd0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
34fe0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
34ff0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
35000 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
35010 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
35020 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
35030 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69 73  itten.  ^If N is
35040 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
35050 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ro [SQLITE_ERROR
35060 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
35070 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69  d no data is wri
35080 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69 7a  tten..** The siz
35090 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28 61  e of the BLOB (a
350a0 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
350b0 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
350c0 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
350d0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
350e0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
350f0 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
35100 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
35110 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 77  ^An attempt to w
35120 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69 72  rite to an expir
35130 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
35140 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
35150 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
35160 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 20  [SQLITE_ABORT]. 
35170 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65 20   ^Writes to the 
35180 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72 72  BLOB that occurr
35190 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  ed.** before the
351a0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 65   [BLOB handle] e
351b0 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20 72  xpired are not r
351c0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68  olled back by th
351d0 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e 20  e.** expiration 
351e0 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20 74  of the handle, t
351f0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
35200 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d 69  those changes mi
35210 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e  ght.** have been
35220 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
35230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
35240 61 74 20 65 78 70 69 72 65 64 20 74 68 65 20 42  at expired the B
35250 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f 72  LOB handle.** or
35260 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70 65   by other indepe
35270 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73  ndent statements
35280 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
35290 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c  cess, sqlite3_bl
352a0 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74 75 72  ob_write() retur
352b0 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  ns SQLITE_OK..**
352c0 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20   Otherwise, an  
352d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
352e0 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  an [extended err
352f0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
35300 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  rned.)^.**.** Th
35310 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
35320 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
35330 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
35340 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
35350 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
35360 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
35370 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
35380 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
35390 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
353a0 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
353b0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
353c0 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
353d0 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
353e0 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
353f0 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
35400 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
35410 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
35420 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a  e behavior..**.*
35430 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
35440 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
35450 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
35460 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c  3_blob_write(sql
35470 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e  ite3_blob *, con
35480 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20  st void *z, int 
35490 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  n, int iOffset);
354a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
354b0 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53  : Virtual File S
354c0 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a 2a  ystem Objects.**
354d0 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66 69  .** A virtual fi
354e0 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20 69  lesystem (VFS) i
354f0 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  s an [sqlite3_vf
35500 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68 61  s] object.** tha
35510 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 6f  t SQLite uses to
35520 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69 74   interact.** wit
35530 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  h the underlying
35540 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
35550 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65 20  m.  Most SQLite 
35560 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74 68  builds come with
35570 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65 66   a.** single def
35580 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69 73  ault VFS that is
35590 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
355a0 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75 74   the host comput
355b0 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73  er..** New VFSes
355c0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
355d0 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67 20  ed and existing 
355e0 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e 72  VFSes can be unr
355f0 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54 68  egistered..** Th
35600 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
35610 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
35620 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ded..**.** ^The 
35630 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
35640 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35650 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
35660 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69 74  o a VFS given it
35670 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d 65  s name..** ^Name
35680 73 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69  s are case sensi
35690 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20  tive..** ^Names 
356a0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
356b0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
356c0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72 65 20  s..** ^If there 
356d0 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e  is no match, a N
356e0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
356f0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
35700 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c  zVfsName is NULL
35710 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
35720 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e 65  t VFS is returne
35730 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20 56 46  d..**.** ^New VF
35740 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65 72  Ses are register
35750 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33 5f  ed with sqlite3_
35760 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 0a  vfs_register()..
35770 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56 46 53  ** ^Each new VFS
35780 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65 66   becomes the def
35790 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65 20  ault VFS if the 
357a0 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69 73  makeDflt flag is
357b0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 61   set..** ^The sa
357c0 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72 65  me VFS can be re
357d0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
357e0 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74 20  e times without 
357f0 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f 20 6d  injury..** ^To m
35800 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67 20  ake an existing 
35810 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65 66  VFS into the def
35820 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73 74  ault VFS, regist
35830 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20 77  er it again.** w
35840 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c 74  ith the makeDflt
35850 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20 74   flag set.  If t
35860 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46 53  wo different VFS
35870 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 73  es with the.** s
35880 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65 67  ame name are reg
35890 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65 68  istered, the beh
358a0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
358b0 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46 53  ed.  If a.** VFS
358c0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
358d0 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74 20  ith a name that 
358e0 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
358f0 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20 74  pty string,.** t
35900 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
35910 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
35920 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74 65 72  *.** ^Unregister
35930 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20   a VFS with the 
35940 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
35950 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61  gister() interfa
35960 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  ce..** ^(If the 
35970 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75  default VFS is u
35980 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f  nregistered, ano
35990 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f 73  ther VFS is chos
359a0 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66  en as.** the def
359b0 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63  ault.  The choic
359c0 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46  e for the new VF
359d0 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 29  S is arbitrary.)
359e0 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66 73  ^.*/.sqlite3_vfs
359f0 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   *sqlite3_vfs_fi
35a00 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  nd(const char *z
35a10 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73 71  VfsName);.int sq
35a20 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
35a30 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  er(sqlite3_vfs*,
35a40 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b 0a   int makeDflt);.
35a50 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
35a60 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69 74  unregister(sqlit
35a70 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e3_vfs*);../*.**
35a80 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
35a90 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  es.**.** The SQL
35aa0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
35ab0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
35ac0 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63 68   thread.** synch
35ad0 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f 75  ronization. Thou
35ae0 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74 65  gh they are inte
35af0 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61  nded for interna
35b00 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
35b10 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c 69  te, code that li
35b20 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c 69  nks against SQLi
35b30 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74 74  te is.** permitt
35b40 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f 66  ed to use any of
35b50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
35b60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
35b70 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63 6f  e source code co
35b80 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65 20  ntains multiple 
35b90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
35ba0 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74 65  ** of these mute
35bb0 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e 20  x routines.  An 
35bc0 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70 6c  appropriate impl
35bd0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
35be0 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d 61   selected automa
35bf0 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70 69  tically at compi
35c00 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68 65 20  le-time.  ^(The 
35c10 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d 70  following.** imp
35c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72 65  lementations are
35c30 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
35c40 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a 2a  e SQLite core:.*
35c50 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
35c60 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
35c70 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _OS2.** <li>   S
35c80 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
35c90 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  EAD.** <li>   SQ
35ca0 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 2a  LITE_MUTEX_W32.*
35cb0 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
35cc0 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f  MUTEX_NOOP.** </
35cd0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ul>)^.**.** ^The
35ce0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
35cf0 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  OP implementatio
35d00 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f  n is a set of ro
35d10 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64  utines.** that d
35d20 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b  oes no real lock
35d30 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f  ing and is appro
35d40 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 69  priate for use i
35d50 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68  n.** a single-th
35d60 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
35d70 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  on.  ^The SQLITE
35d80 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53  _MUTEX_OS2,.** S
35d90 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52  QLITE_MUTEX_PTHR
35da0 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f  EAD, and SQLITE_
35db0 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d  MUTEX_W32 implem
35dc0 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
35dd0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
35de0 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e   use on OS/2, Un
35df0 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e  ix, and Windows.
35e00 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
35e10 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
35e20 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4d  ith the SQLITE_M
35e30 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65 70  UTEX_APPDEF prep
35e40 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63 72  rocessor.** macr
35e50 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68 20  o defined (with 
35e60 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  "-DSQLITE_MUTEX_
35e70 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65 6e  APPDEF=1"), then
35e80 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70   no mutex.** imp
35e90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 69  lementation is i
35ea0 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68 65  ncluded with the
35eb0 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68 69   library. In thi
35ec0 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61 70  s case the.** ap
35ed0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
35ee0 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20 6d  upply a custom m
35ef0 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
35f00 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ion using the.**
35f10 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
35f20 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f 66  MUTEX] option of
35f30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   the sqlite3_con
35f40 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  fig() function.*
35f50 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67  * before calling
35f60 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
35f70 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74 68  ize() or any oth
35f80 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65  er public sqlite
35f90 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  3_.** function t
35fa0 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  hat calls sqlite
35fb0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 29  3_initialize().)
35fc0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
35fd0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
35fe0 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f 63  () routine alloc
35ff0 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d 75  ates a new.** mu
36000 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73 20  tex and returns 
36010 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
36020 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73 20   ^If it returns 
36030 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65 61  NULL.** that mea
36040 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78 20  ns that a mutex 
36050 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c 6c  could not be all
36060 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74 65  ocated.  ^SQLite
36070 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20  .** will unwind 
36080 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65  its stack and re
36090 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 20  turn an error.  
360a0 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ^(The argument.*
360b0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  * to sqlite3_mut
360c0 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e  ex_alloc() is on
360d0 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
360e0 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  er constants:.**
360f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
36100 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46    SQLITE_MUTEX_F
36110 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  AST.** <li>  SQL
36120 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
36130 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
36140 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
36150 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20  _MASTER.** <li> 
36160 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
36170 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e  ATIC_MEM.** <li>
36180 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
36190 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c  TATIC_MEM2.** <l
361a0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
361b0 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20  _STATIC_PRNG.** 
361c0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
361d0 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a  EX_STATIC_LRU.**
361e0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
361f0 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a  TEX_STATIC_LRU2.
36200 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
36210 20 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f 20   ^The first two 
36220 63 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49 54  constants (SQLIT
36230 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64  E_MUTEX_FAST and
36240 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
36250 43 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75 73  CURSIVE).** caus
36260 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
36270 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61 74  alloc() to creat
36280 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65 78  e.** a new mutex
36290 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74 65  .  ^The new mute
362a0 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20 77  x is recursive w
362b0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
362c0 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69 73  _RECURSIVE.** is
362d0 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e 65   used but not ne
362e0 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68 65  cessarily so whe
362f0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  n SQLITE_MUTEX_F
36300 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a 20  AST is used..** 
36310 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  The mutex implem
36320 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  entation does no
36330 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61  t need to make a
36340 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
36350 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d  between SQLITE_M
36360 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61  UTEX_RECURSIVE a
36370 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
36380 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a  FAST if it does.
36390 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20  ** not want to. 
363a0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e   ^SQLite will on
363b0 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65 63  ly request a rec
363c0 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e 0a  ursive mutex in.
363d0 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20 69  ** cases where i
363e0 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20 6f  t really needs o
363f0 6e 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74 65  ne.  ^If a faste
36400 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20  r non-recursive 
36410 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
36420 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  ntation is avail
36430 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74  able on the host
36440 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d   platform, the m
36450 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a  utex subsystem.*
36460 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73  * might return s
36470 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72  uch a mutex in r
36480 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54  esponse to SQLIT
36490 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a  E_MUTEX_FAST..**
364a0 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20 61  .** ^The other a
364b0 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72  llowed parameter
364c0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  s to sqlite3_mut
364d0 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79 74  ex_alloc() (anyt
364e0 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74 68  hing other.** th
364f0 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  an SQLITE_MUTEX_
36500 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f  FAST and SQLITE_
36510 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
36520 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a 20   each return.** 
36530 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
36540 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69 6e  tatic preexistin
36550 67 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20 73  g mutex.  ^Six s
36560 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
36570 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65  e.** used by the
36580 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e   current version
36590 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74   of SQLite.  Fut
365a0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
365b0 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64  SQLite.** may ad
365c0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61  d additional sta
365d0 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74  tic mutexes.  St
365e0 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
365f0 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a   for internal.**
36600 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f   use by SQLite o
36610 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
36620 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ns that use SQLi
36630 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  te mutexes shoul
36640 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68  d.** use only th
36650 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
36660 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  s returned by SQ
36670 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
36680 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  or.** SQLITE_MUT
36690 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a  EX_RECURSIVE..**
366a0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 69  .** ^Note that i
366b0 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e  f one of the dyn
366c0 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d  amic mutex param
366d0 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55  eters (SQLITE_MU
366e0 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53  TEX_FAST.** or S
366f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
36700 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74  RSIVE) is used t
36710 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  hen sqlite3_mute
36720 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74  x_alloc().** ret
36730 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74  urns a different
36740 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20   mutex on every 
36750 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72 20  call.  ^But for 
36760 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  the static.** mu
36770 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73  tex types, the s
36780 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74  ame mutex is ret
36790 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63  urned on every c
367a0 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  all that has.** 
367b0 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75  the same type nu
367c0 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
367d0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66   sqlite3_mutex_f
367e0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65  ree() routine de
367f0 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76  allocates a prev
36800 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61  iously.** alloca
36810 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  ted dynamic mute
36820 78 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20 63  x.  ^SQLite is c
36830 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f  areful to deallo
36840 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79  cate every.** dy
36850 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74  namic mutex that
36860 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 20   it allocates.  
36870 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  The dynamic mute
36880 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  xes must not be 
36890 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74  in.** use when t
368a0 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  hey are dealloca
368b0 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e 67  ted.  Attempting
368c0 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61   to deallocate a
368d0 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78   static.** mutex
368e0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
368f0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20  fined behavior. 
36900 20 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64   ^SQLite never d
36910 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20  eallocates.** a 
36920 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
36930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36940 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 61  _mutex_enter() a
36950 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nd sqlite3_mutex
36960 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73 20  _try() routines 
36970 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65 6e  attempt.** to en
36980 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e 49  ter a mutex.  ^I
36990 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
369a0 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74 68   is already with
369b0 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a 2a  in the mutex,.**
369c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
369d0 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f 63  nter() will bloc
369e0 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  k and sqlite3_mu
369f0 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20 72  tex_try() will r
36a00 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
36a10 42 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c 69  BUSY.  ^The sqli
36a20 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
36a30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36a40 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a  s [SQLITE_OK].**
36a50 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75 6c   upon successful
36a60 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65 78   entry.  ^(Mutex
36a70 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
36a80 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
36a90 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62  _RECURSIVE can b
36aa0 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70  e entered multip
36ab0 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20  le times by the 
36ac0 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20  same thread..** 
36ad0 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74 68  In such cases th
36ae0 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73 74  e,.** mutex must
36af0 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65 71   be exited an eq
36b00 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  ual number of ti
36b10 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74 68  mes before anoth
36b20 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61 6e  er thread.** can
36b30 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66 20   enter.)^  ^(If 
36b40 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
36b50 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61  tries to enter a
36b60 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  ny other.** kind
36b70 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74   of mutex more t
36b80 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65  han once, the be
36b90 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
36ba0 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ned..** SQLite w
36bb0 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69  ill never exhibi
36bc0 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69  t.** such behavi
36bd0 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73  or in its own us
36be0 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e 0a  e of mutexes.)^.
36bf0 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79 73  **.** ^(Some sys
36c00 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70 6c  tems (for exampl
36c10 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20 64  e, Windows 95) d
36c20 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74 68  o not support th
36c30 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  e operation.** i
36c40 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73 71  mplemented by sq
36c50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
36c60 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79 73  ).  On those sys
36c70 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d 75  tems, sqlite3_mu
36c80 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69 6c  tex_try().** wil
36c90 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
36ca0 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54 68  SQLITE_BUSY.  Th
36cb0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
36cc0 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a 20  ly ever uses.** 
36cd0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36ce0 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d 69  y() as an optimi
36cf0 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20 69  zation so this i
36d00 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65 68  s acceptable beh
36d10 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  avior.)^.**.** ^
36d20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
36d30 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69 6e  x_leave() routin
36d40 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78 20  e exits a mutex 
36d50 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65 76  that was.** prev
36d60 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20 62  iously entered b
36d70 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
36d80 64 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61 76  d.   ^(The behav
36d90 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
36da0 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78  ned if the mutex
36db0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
36dc0 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
36dd0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  .** calling thre
36de0 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72  ad or is not cur
36df0 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64  rently allocated
36e00 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
36e10 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68 65  * never do eithe
36e20 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  r.)^.**.** ^If t
36e30 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  he argument to s
36e40 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
36e50 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d 75  er(), sqlite3_mu
36e60 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a 2a  tex_try(), or.**
36e70 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c   sqlite3_mutex_l
36e80 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c 4c  eave() is a NULL
36e90 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 61   pointer, then a
36ea0 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  ll three routine
36eb0 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20 6e  s.** behave as n
36ec0 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  o-ops..**.** See
36ed0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
36ee0 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61 6e  mutex_held()] an
36ef0 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d [sqlite3_mutex
36f00 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a  _notheld()]..*/.
36f10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73  sqlite3_mutex *s
36f20 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
36f30 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  oc(int);.void sq
36f40 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65  lite3_mutex_free
36f50 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
36f60 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d  ;.void sqlite3_m
36f70 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69 74  utex_enter(sqlit
36f80 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20  e3_mutex*);.int 
36f90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36fa0 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  y(sqlite3_mutex*
36fb0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36fc0 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c 69  mutex_leave(sqli
36fd0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a  te3_mutex*);../*
36fe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
36ff0 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  tex Methods Obje
37000 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
37010 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
37020 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20 74  ucture defines t
37030 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75  he low-level rou
37040 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f  tines.** used to
37050 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73   allocate and us
37060 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a  e mutexes..**.**
37070 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65   Usually, the de
37080 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c  fault mutex impl
37090 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76  ementations prov
370a0 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  ided by SQLite a
370b0 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74  re.** sufficient
370c0 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75 73  , however the us
370d0 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f  er has the optio
370e0 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e  n of substitutin
370f0 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d  g a custom.** im
37100 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
37110 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70   specialized dep
37120 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74  loyments or syst
37130 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53 51  ems for which SQ
37140 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
37150 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74 61   provide a suita
37160 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
37170 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  on. In this case
37180 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72  , the user.** cr
37190 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61  eates and popula
371a0 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  tes an instance 
371b0 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
371c0 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20  e to pass.** to 
371d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
371e0 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20   along with the 
371f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
37200 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  UTEX] option..**
37210 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61   Additionally, a
37220 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
37230 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61 6e  is structure can
37240 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a   be used as an.*
37250 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c  * output variabl
37260 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20  e when querying 
37270 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74  the system for t
37280 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78  he current mutex
37290 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
372a0 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53  on, using the [S
372b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
372c0 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a  MUTEX] option..*
372d0 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78  *.** ^The xMutex
372e0 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66 69  Init method defi
372f0 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
37300 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
37310 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
37320 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61  ystem initializa
37330 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c 69  tion by the sqli
37340 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
37350 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 54   function..** ^T
37360 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72 6f  he xMutexInit ro
37370 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 20 62  utine is calle b
37380 79 20 53 51 4c 69 74 65 20 65 78 61 63 74 6c 79  y SQLite exactly
37390 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a 2a   once for each.*
373a0 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  * effective call
373b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69   to [sqlite3_ini
373c0 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a  tialize()]..**.*
373d0 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64  * ^The xMutexEnd
373e0 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20   method defined 
373f0 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
37400 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a  e is invoked as.
37410 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65  ** part of syste
37420 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74 68  m shutdown by th
37430 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
37440 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20 54  wn() function. T
37450 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
37460 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65 74  tion of this met
37470 68 6f 64 20 69 73 20 65 78 70 65 63 74 65 64 20  hod is expected 
37480 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20 6f  to release all o
37490 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72 65  utstanding.** re
374a0 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65 64  sources obtained
374b0 20 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d 65   by the mutex me
374c0 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74 61  thods implementa
374d0 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c 79  tion, especially
374e0 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69 6e  .** those obtain
374f0 65 64 20 62 79 20 74 68 65 20 78 4d 75 74 65 78  ed by the xMutex
37500 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20 5e 54  Init method.  ^T
37510 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a 2a  he xMutexEnd().*
37520 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  * interface is i
37530 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f  nvoked exactly o
37540 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c  nce for each cal
37550 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68  l to [sqlite3_sh
37560 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a  utdown()]..**.**
37570 20 5e 28 54 68 65 20 72 65 6d 61 69 6e 69 6e 67   ^(The remaining
37580 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64   seven methods d
37590 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
375a0 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65 78  tructure (xMutex
375b0 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78  Alloc,.** xMutex
375c0 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65  Free, xMutexEnte
375d0 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d  r, xMutexTry, xM
375e0 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65  utexLeave, xMute
375f0 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75  xHeld and.** xMu
37600 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c  texNotheld) impl
37610 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77  ement the follow
37620 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 28  ing interfaces (
37630 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a  respectively):.*
37640 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
37650 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
37660 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c  tex_alloc()] </l
37670 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
37680 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
37690 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  e()] </li>.**   
376a0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
376b0 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f  utex_enter()] </
376c0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
376d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
376e0 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  y()] </li>.**   
376f0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37700 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f  utex_leave()] </
37710 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
37720 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
37730 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ld()] </li>.**  
37740 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37750 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d  mutex_notheld()]
37760 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29   </li>.** </ul>)
37770 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79  ^.**.** The only
37780 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 74   difference is t
37790 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 20 73  hat the public s
377a0 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63 74  qlite3_XXX funct
377b0 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64 0a  ions enumerated.
377c0 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74 6c  ** above silentl
377d0 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e 76  y ignore any inv
377e0 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70 61  ocations that pa
377f0 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ss a NULL pointe
37800 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
37810 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61  a valid mutex ha
37820 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65 6d  ndle. The implem
37830 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
37840 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64   methods defined
37850 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72 75  .** by this stru
37860 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72 65  cture are not re
37870 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c 65  quired to handle
37880 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20   this case, the 
37890 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70 61  results.** of pa
378a0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
378b0 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
378c0 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68 61  a valid mutex ha
378d0 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69 6e  ndle are undefin
378e0 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20 69  ed.** (i.e. it i
378f0 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f 20  s acceptable to 
37900 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c 65  provide an imple
37910 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 73  mentation that s
37920 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20 69  egfaults if.** i
37930 74 20 69 73 20 70 61 73 73 65 64 20 61 20 4e 55  t is passed a NU
37940 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a  LL pointer)..**.
37950 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69  ** The xMutexIni
37960 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  t() method must 
37970 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
37980 5e 49 74 20 6d 75 73 74 20 62 65 20 68 61 72 6d  ^It must be harm
37990 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  less to.** invok
379a0 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d  e xMutexInit() m
379b0 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74  utiple times wit
379c0 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
379d0 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75 74  cess and without
379e0 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67 20  .** intervening 
379f0 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78 45  calls to xMutexE
37a00 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61 6e  nd().  Second an
37a10 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
37a20 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78 49  ls to.** xMutexI
37a30 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e 6f  nit() must be no
37a40 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78 4d 75  -ops..**.** ^xMu
37a50 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 6e  texInit() must n
37a60 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65  ot use SQLite me
37a70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
37a80 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  ([sqlite3_malloc
37a90 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20 61  ()].** and its a
37aa0 73 73 6f 63 69 61 74 65 73 29 2e 20 20 5e 53 69  ssociates).  ^Si
37ab0 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78 41  milarly, xMutexA
37ac0 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74 20  lloc() must not 
37ad0 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72  use SQLite memor
37ae0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  y.** allocation 
37af0 66 6f 72 20 61 20 73 74 61 74 69 63 20 6d 75 74  for a static mut
37b00 65 78 2e 20 20 5e 48 6f 77 65 76 65 72 20 78 4d  ex.  ^However xM
37b10 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20  utexAlloc() may 
37b20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65  use SQLite.** me
37b30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
37b40 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20 72 65  for a fast or re
37b50 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a  cursive mutex..*
37b60 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
37b70 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d 75  l invoke the xMu
37b80 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 20  texEnd() method 
37b90 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68  when [sqlite3_sh
37ba0 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a 20  utdown()] is.** 
37bb0 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c 79  called, but only
37bc0 20 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 61   if the prior ca
37bd0 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 74  ll to xMutexInit
37be0 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45   returned SQLITE
37bf0 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 65  _OK..** If xMute
37c00 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 61  xInit fails in a
37c10 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 78  ny way, it is ex
37c20 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e 20  pected to clean 
37c30 75 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 0a  up after itself.
37c40 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 75  ** prior to retu
37c50 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 65  rning..*/.typede
37c60 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
37c70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73  _mutex_methods s
37c80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
37c90 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
37ca0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
37cb0 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75  ds {.  int (*xMu
37cc0 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a  texInit)(void);.
37cd0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e    int (*xMutexEn
37ce0 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69  d)(void);.  sqli
37cf0 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75  te3_mutex *(*xMu
37d00 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a  texAlloc)(int);.
37d10 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46    void (*xMutexF
37d20 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  ree)(sqlite3_mut
37d30 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  ex *);.  void (*
37d40 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c  xMutexEnter)(sql
37d50 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
37d60 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79   int (*xMutexTry
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 76 6f 69 64 20 28 2a 78 4d 75  *);.  void (*xMu
37d90 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65  texLeave)(sqlite
37da0 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e  3_mutex *);.  in
37db0 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28  t (*xMutexHeld)(
37dc0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
37dd0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
37de0 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33  Notheld)(sqlite3
37df0 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f  _mutex *);.};../
37e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
37e10 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f  utex Verificatio
37e20 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
37e30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
37e40 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73 71  ex_held() and sq
37e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
37e60 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a 2a  eld() routines.*
37e70 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  * are intended f
37e80 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 73  or use inside as
37e90 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
37ea0 73 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20  s.  ^The SQLite 
37eb0 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75 73  core.** never us
37ec0 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  es these routine
37ed0 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65 20  s except inside 
37ee0 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64 20  an assert() and 
37ef0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
37f00 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20 66  are advised to f
37f10 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20 6f  ollow the lead o
37f20 66 20 74 68 65 20 63 6f 72 65 2e 20 20 5e 54 68  f the core.  ^Th
37f30 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f 6e  e SQLite core on
37f40 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20 69  ly.** provides i
37f50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
37f60 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
37f70 73 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  s when it is com
37f80 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  piled.** with th
37f90 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 66  e SQLITE_DEBUG f
37fa0 6c 61 67 2e 20 20 5e 45 78 74 65 72 6e 61 6c 20  lag.  ^External 
37fb0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
37fc0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e 6c  tions.** are onl
37fd0 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  y required to pr
37fe0 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75 74  ovide these rout
37ff0 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f 44  ines if SQLITE_D
38000 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69 6e  EBUG is.** defin
38010 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55 47  ed and if NDEBUG
38020 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64 2e   is not defined.
38030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
38040 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72 65  utines should re
38050 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65  turn true if the
38060 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72 20   mutex in their 
38070 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20 68  argument.** is h
38080 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64 2c  eld or not held,
38090 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20 62   respectively, b
380a0 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  y the calling th
380b0 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  read..**.** ^The
380c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
380d0 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20  is not required 
380e0 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72 73  to provided vers
380f0 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ions of these.**
38100 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 61   routines that a
38110 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49 66  ctually work. If
38120 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
38130 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f  ion does not pro
38140 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a 20  vide working.** 
38150 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
38160 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20 73  e routines, it s
38170 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20 70  hould at least p
38180 72 6f 76 69 64 65 20 73 74 75 62 73 20 74 68 61  rovide stubs tha
38190 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74 75  t always.** retu
381a0 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74 20  rn true so that 
381b0 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65 74  one does not get
381c0 20 73 70 75 72 69 6f 75 73 20 61 73 73 65 72 74   spurious assert
381d0 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a 2a  ion failures..**
381e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75  .** ^If the argu
381f0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
38200 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73 20  mutex_held() is 
38210 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
38220 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hen.** the routi
38230 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ne should return
38240 20 31 2e 20 20 20 54 68 69 73 20 73 65 65 6d 73   1.   This seems
38250 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69   counter-intuiti
38260 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61  ve since.** clea
38270 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61  rly the mutex ca
38280 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20  nnot be held if 
38290 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  it does not exis
382a0 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74  t.  But the.** t
382b0 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75  he reason the mu
382c0 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69  tex does not exi
382d0 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68  st is because th
382e0 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a  e build is not.*
382f0 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e  * using mutexes.
38300 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20    And we do not 
38310 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28  want the assert(
38320 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  ) containing the
38330 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
38340 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
38350 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e   to fail, so a n
38360 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69  on-zero return i
38370 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72  s.** the appropr
38380 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f  iate thing to do
38390 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
383a0 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a  mutex_notheld().
383b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  ** interface sho
383c0 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  uld also return 
383d0 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e  1 when given a N
383e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
383f0 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 69  #ifndef NDEBUG.i
38400 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
38410 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  _held(sqlite3_mu
38420 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
38430 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
38440 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
38450 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
38460 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
38470 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Types.**.** The 
38480 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
38490 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66 61 63  lloc()] interfac
384a0 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  e takes a single
384b0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 69   argument.** whi
384c0 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  ch is one of the
384d0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
384e0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ants..**.** The 
384f0 73 65 74 20 6f 66 20 73 74 61 74 69 63 20 6d 75  set of static mu
38500 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e 67 65  texes may change
38510 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69 74 65   from one SQLite
38520 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 0a   release to the.
38530 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
38540 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76 65 72  ations that over
38550 72 69 64 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ride the built-i
38560 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20 6d 75  n mutex logic mu
38570 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61 72 65  st be.** prepare
38580 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61 74 65  d to accommodate
38590 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
385a0 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f 0a 23  ic mutexes..*/.#
385b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
385c0 54 45 58 5f 46 41 53 54 20 20 20 20 20 20 20 20  TEX_FAST        
385d0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
385e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
385f0 52 53 49 56 45 20 20 20 20 20 20 20 20 31 0a 23  RSIVE        1.#
38600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
38610 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
38620 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  R    2.#define S
38630 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
38640 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33 20 20  IC_MEM       3  
38650 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  /* sqlite3_mallo
38660 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  c() */.#define S
38670 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
38680 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34 20 20  IC_MEM2      4  
38690 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f 0a 23  /* NOT USED */.#
386a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55  define SQLITE_MU
386b0 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45 4e 20  TEX_STATIC_OPEN 
386c0 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
386d0 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20 2a 2f  e3BtreeOpen() */
386e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
386f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e  MUTEX_STATIC_PRN
38700 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  G      5  /* sql
38710 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20 2a 2f  ite3_random() */
38720 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38730 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
38740 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c 72 75         6  /* lru
38750 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 23 64   page list */.#d
38760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54  efine SQLITE_MUT
38770 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 20 20  EX_STATIC_LRU2  
38780 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20 70 61      7  /* lru pa
38790 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  ge list */../*.*
387a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
387b0 69 65 76 65 20 74 68 65 20 6d 75 74 65 78 20 66  ieve the mutex f
387c0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
387d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
387e0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
387f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
38800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
38810 74 65 78 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  tex] object that
38820 20 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 65 73 20   .** serializes 
38830 61 63 63 65 73 73 20 74 6f 20 74 68 65 20 5b 64  access to the [d
38840 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38850 6f 6e 5d 20 67 69 76 65 6e 20 69 6e 20 74 68 65  on] given in the
38860 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77 68 65   argument.** whe
38870 6e 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  n the [threading
38880 20 6d 6f 64 65 5d 20 69 73 20 53 65 72 69 61 6c   mode] is Serial
38890 69 7a 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ized..** ^If the
388a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
388b0 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] is Single-thre
388c0 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74 68 72 65  ad or Multi-thre
388d0 61 64 20 74 68 65 6e 20 74 68 69 73 0a 2a 2a 20  ad then this.** 
388e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
388f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
38900 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
38910 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74   *sqlite3