/ Hex Artifact Content
Login

Artifact 4f72e39f1edeccaf2a5913483bce2f704492b892:


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 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
4f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4f60: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
4f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
4f80: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
4f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4fa0: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
4fb0: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
4fc0: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
4fd0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
4fe0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
4ff0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5000: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5010: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5020: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5030: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5040: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5050: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5060: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5070: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5080: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f  ameter to the xO
5090: 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  pen method of th
50a0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
50b0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
50c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
50d0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
50e0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
50f0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5100: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5120: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5130: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
5140: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5150: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5160: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5170: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5180: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
5190: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
51a0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
51b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
51c0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
51d0: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
51e0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
51f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5200: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
5210: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
5220: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5240: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
5250: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
5260: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5280: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
5290: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
52a0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
52b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
52c0: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
52d0: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
52e0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
52f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5300: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
5310: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
5320: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
5350: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
5360: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5380: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
5390: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
53a0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
53b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
53c0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
53d0: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
53e0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
53f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5400: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
5410: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
5420: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5440: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
5450: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
5460: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5470: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5480: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5490: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
54a0: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
54b0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
54c0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
54d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
54e0: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
54f0: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
5500: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5510: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5530: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
5540: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
5550: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5560: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f  _open_v2() */../
5570: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
5580: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
5590: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  stics.**.** The 
55a0: 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74  xDeviceCapabilit
55b0: 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ies method of th
55c0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
55d0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
55e0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
55f0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
5600: 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65  ector of the the
5610: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
5620: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
5630: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
5640: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
5650: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
5660: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
5670: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
5680: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5690: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
56a0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
56b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
56c0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
56d0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
56e0: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
56f0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
5700: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
5710: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
5720: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
5730: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
5740: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
5750: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
5760: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
5770: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
5780: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
5790: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
57a0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
57b0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
57c0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
57d0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
57e0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
57f0: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
5800: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
5810: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
5820: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
5830: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
5840: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
5850: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
5860: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5870: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
5880: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
5890: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
58a0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
58b0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
58c0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
58d0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64   xWrite()..*/.#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
58f0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
5900: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5920: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5930: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5940: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5950: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
5960: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
5970: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5980: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
5990: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
59b0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
59c0: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
59d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
59e0: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
59f0: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a10: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5a20: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a40: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
5a50: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
5a60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a70: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
5a80: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
5a90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5aa0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
5ab0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5ad0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5ae0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f     0x00000400../
5af0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5b00: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
5b10: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
5b20: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
5b30: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5b40: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
5b50: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
5b60: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
5b70: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
5b80: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
5b90: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
5ba0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
5bb0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5bc0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
5bd0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
5be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5bf0: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
5c00: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
5c10: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
5c20: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
5c30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
5c40: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
5c50: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
5c60: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
5c70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5c80: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
5c90: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
5ca0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
5cb0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
5cc0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
5cd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5ce0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
5cf0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
5d00: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
5d10: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5d20: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
5d30: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
5d40: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
5d50: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
5d60: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
5d70: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
5d80: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
5d90: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
5da0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
5db0: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
5dc0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
5dd0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
5de0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
5df0: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
5e00: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
5e10: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
5e20: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
5e30: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
5e40: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
5e50: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
5e60: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
5e70: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
5e80: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
5e90: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
5ea0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
5eb0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
5ec0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ed0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
5ee0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
5ef0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
5f00: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
5f10: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
5f20: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
5f30: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
5f40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5f50: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
5f60: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
5f70: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
5f80: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
5f90: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
5fa0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
5fb0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
5fc0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
5fd0: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
5fe0: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
5ff0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
6000: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
6010: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
6020: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
6030: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
6040: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
6050: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
6060: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
6070: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
6080: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
6090: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
60a0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
60b0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
60c0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
60d0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
60e0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
60f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
6100: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
6110: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
6120: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
6130: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
6140: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
6150: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
6160: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
6170: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
6180: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6190: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
61a0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
61b0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
61c0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
61d0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
61e0: 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  fs] xOpen method
61f0: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
6200: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6210: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
6220: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
6230: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
6240: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6250: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
6260: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
6270: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
6280: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
6290: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
62a0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
62b0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
62c0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
62d0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
62e0: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
62f0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
6300: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
6310: 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e  .** If the xOpen
6320: 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65   method sets the
6330: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
6340: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a  ethods element .
6350: 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ** to a non-NULL
6360: 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74   pointer, then t
6370: 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  he sqlite3_io_me
6380: 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74  thods.xClose met
6390: 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e  hod.** may be in
63a0: 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68  voked even if th
63b0: 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64  e xOpen reported
63c0: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
63d0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
63e0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
63f0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
6400: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
6410: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72   xOpen.** is for
6420: 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65   the xOpen to se
6430: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
6440: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
6450: 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ent to NULL..**.
6460: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
6470: 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d  ument to xSync m
6480: 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51  ay be one of [SQ
6490: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
64a0: 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
64b0: 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65  SYNC_FULL].  The
64c0: 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73   first choice is
64d0: 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e   the normal fsyn
64e0: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  c()..** The seco
64f0: 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d  nd choice is a M
6500: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6510: 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51  llsync.  The [SQ
6520: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6530: 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20  LY].** flag may 
6540: 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e  be ORed in to in
6550: 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79  dicate that only
6560: 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65   the data of the
6570: 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74   file.** and not
6580: 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73   its inode needs
6590: 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a   to be synced..*
65a0: 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72  *.** The integer
65b0: 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b   values to xLock
65c0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
65d0: 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c   are one of.** <
65e0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
65f0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a  ITE_LOCK_NONE],.
6600: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6610: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
6620: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6630: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a  CK_RESERVED],.**
6640: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6650: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a  CK_PENDING], or.
6660: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6670: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e  LOCK_EXCLUSIVE].
6680: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f  .** </ul>.** xLo
6690: 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74  ck() increases t
66a0: 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b  he lock. xUnlock
66b0: 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65  () decreases the
66c0: 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43   lock..** The xC
66d0: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
66e0: 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73  () method checks
66f0: 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74   whether any dat
6700: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6710: 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74  ,.** either in t
6720: 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69  his process or i
6730: 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f  n some other pro
6740: 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67  cess, is holding
6750: 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20   a RESERVED,.** 
6760: 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c  PENDING, or EXCL
6770: 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68  USIVE lock on th
6780: 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75  e file.  It retu
6790: 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73  rns true.** if s
67a0: 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74  uch a lock exist
67b0: 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65  s and false othe
67c0: 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rwise..**.** The
67d0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
67e0: 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65  method is a gene
67f0: 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68  ric interface th
6800: 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d  at allows custom
6810: 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  .** VFS implemen
6820: 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63  tations to direc
6830: 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f  tly control an o
6840: 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74  pen file using t
6850: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6860: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69  ile_control()] i
6870: 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73  nterface.  The s
6880: 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d  econd "op" argum
6890: 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74  ent is an.** int
68a0: 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68  eger opcode.  Th
68b0: 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
68c0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f   is a generic po
68d0: 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74  inter intended t
68e0: 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20  o.** point to a 
68f0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d  structure that m
6900: 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d  ay contain argum
6910: 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e  ents or space in
6920: 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69   which to.** wri
6930: 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73  te return values
6940: 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65  .  Potential use
6950: 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72  s for xFileContr
6960: 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a  ol() might be.**
6970: 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e   functions to en
6980: 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f  able blocking lo
6990: 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74  cks with timeout
69a0: 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  s, to change the
69b0: 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61  .** locking stra
69c0: 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c  tegy (for exampl
69d0: 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c  e to use dot-fil
69e0: 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71  e locks), to inq
69f0: 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68  uire.** about th
6a00: 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f  e status of a lo
6a10: 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20  ck, or to break 
6a20: 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68  stale locks.  Th
6a30: 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65  e SQLite.** core
6a40: 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70   reserves all op
6a50: 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20  codes less than 
6a60: 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20  100 for its own 
6a70: 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54  use..** A [SQLIT
6a80: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
6a90: 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  E | list of opco
6aa0: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
6ab0: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
6ac0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
6ad0: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
6ae0: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
6af0: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
6b00: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
6b10: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
6b20: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
6b30: 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  cts..**.** The x
6b40: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
6b50: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
6b60: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
6b70: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
6b80: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
6b90: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
6ba0: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
6bb0: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
6bc0: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
6bd0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
6be0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
6bf0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
6c00: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
6c10: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
6c20: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
6c30: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
6c40: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
6c50: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
6c60: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
6c70: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
6c80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6c90: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
6ca0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6cb0: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
6cc0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6cd0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
6ce0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6cf0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
6d00: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d10: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
6d40: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d50: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
6d60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6d70: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
6d80: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6d90: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
6da0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6db0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6dc0: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
6dd0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6de0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
6df0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6e00: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
6e10: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6e20: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
6e30: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
6e40: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6e50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
6e60: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
6e70: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
6e80: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
6e90: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
6ea0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
6eb0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
6ec0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
6ed0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
6ee0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
6ef0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6f00: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6f10: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
6f20: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
6f30: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
6f40: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
6f50: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
6f60: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
6f70: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
6f80: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
6f90: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
6fa0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
6fb0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6fc0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
6fd0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
6fe0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
6ff0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
7000: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
7010: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
7020: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
7030: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
7040: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
7050: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
7060: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
7070: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
7080: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
7090: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
70a0: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
70b0: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
70c0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
70d0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
70e0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
70f0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
7100: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
7110: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
7120: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
7130: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
7140: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7150: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
7160: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
7170: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
7180: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
7190: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
71a0: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
71b0: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
71c0: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
71d0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
71e0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
71f0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
7200: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
7210: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
7220: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
7230: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7240: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7250: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
7260: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
7270: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
7280: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
7290: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
72a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
72b0: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
72c0: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
72d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
72e0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
72f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
7300: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7310: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
7320: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
7330: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
7340: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
7350: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
7360: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
7370: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
7380: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
7390: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
73a0: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
73b0: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
73c0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
73d0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
73e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
73f0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
7400: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
7410: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7420: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
7430: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4f  */.  int (*xShmO
7440: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  pen)(sqlite3_fil
7450: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  e*);.  int (*xSh
7460: 6d 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  mSize)(sqlite3_f
7470: 69 6c 65 2a 2c 20 69 6e 74 20 72 65 71 53 69 7a  ile*, int reqSiz
7480: 65 2c 20 69 6e 74 20 2a 70 4e 65 77 53 69 7a 65  e, int *pNewSize
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 47  );.  int (*xShmG
74a0: 65 74 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  et)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 20 72 65 71 53 69 7a 65 2c 20  *, int reqSize, 
74c0: 69 6e 74 20 2a 70 53 69 7a 65 2c 20 76 6f 69 64  int *pSize, void
74d0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
74e0: 69 6e 74 20 28 2a 78 53 68 6d 52 65 6c 65 61 73  int (*xShmReleas
74f0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7500: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
7510: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
7520: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
7530: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
7540: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
7550: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
7560: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7570: 2a 78 53 68 6d 43 6c 6f 73 65 29 28 73 71 6c 69  *xShmClose)(sqli
7580: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
7590: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
75a0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
75b0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
75c0: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41  sion 2 */.  /* A
75d0: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64  dditional method
75e0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
75f0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
7600: 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
7610: 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72  API3REF: Standar
7620: 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f  d File Control O
7630: 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  pcodes.**.** The
7640: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
7650: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73  ants are opcodes
7660: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f   for the xFileCo
7670: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20  ntrol method.** 
7680: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
7690: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
76a0: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b  ct and for the [
76b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
76c0: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  trol()].** inter
76d0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
76e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
76f0: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
7700: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
7710: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
7720: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
7730: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7740: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
7750: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
7760: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
7770: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
7780: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
7790: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
77a0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
77b0: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
77c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
77d0: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
77e0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
77f0: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
7800: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
7810: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
7820: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
7830: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
7840: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
7850: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
7860: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
7870: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  en SQLITE_TEST.*
7880: 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  * is defined..**
7890: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
78a0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
78b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
78c0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
78d0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
78e0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
78f0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
7900: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
7910: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
7920: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
7930: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
7940: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
7950: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
7960: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
7970: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
7980: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
7990: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
79a0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
79b0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
79c0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
79d0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
79e0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
79f0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
7a00: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
7a10: 66 61 73 74 65 72 2e 0a 2a 2f 0a 23 64 65 66 69  faster..*/.#defi
7a20: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
7a30: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
7a40: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
7a50: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
7a60: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69  ILE      2.#defi
7a70: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
7a80: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
7a90: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
7aa0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
7ab0: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
7ac0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
7ad0: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
7ae0: 20 35 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   5../*.** CAPI3R
7af0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
7b00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
7b10: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
7b20: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
7b30: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
7b40: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
7b50: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
7b60: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
7b70: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
7b80: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
7b90: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
7ba0: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
7bb0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
7bc0: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
7bd0: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
7be0: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
7bf0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
7c00: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
7c10: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
7c20: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
7c30: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
7c40: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7c50: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
7c60: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
7c70: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7c80: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
7c90: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
7ca0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
7cb0: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
7cc0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
7cd0: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
7ce0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
7cf0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
7d00: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
7d10: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
7d20: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
7d30: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
7d40: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
7d50: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20   system"..**.** 
7d60: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
7d70: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
7d80: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
7d90: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
7da0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
7db0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
7dc0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
7dd0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
7de0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
7df0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
7e00: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
7e10: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
7e20: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
7e30: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
7e40: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7e50: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
7e60: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
7e70: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
7e80: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
7e90: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
7ea0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7eb0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
7ec0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
7ed0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
7ee0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
7ef0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
7f00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
7f10: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
7f20: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
7f30: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
7f40: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
7f50: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
7f60: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
7f70: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
7f80: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
7f90: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
7fa0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
7fb0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
7fc0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
7fd0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
7fe0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
7ff0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
8000: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
8010: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
8020: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
8030: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
8040: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
8050: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
8060: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
8070: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
8080: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
8090: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
80a0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
80b0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
80c0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
80d0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
80e0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
80f0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
8100: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
8110: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
8120: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
8130: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
8140: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
8150: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
8160: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
8170: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
8180: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
8190: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
81a0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
81b0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
81c0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
81d0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
81e0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
81f0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
8200: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
8210: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
8220: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
8230: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
8240: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
8250: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
8260: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
8270: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  dules..**.** SQL
8280: 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74  ite will guarant
8290: 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  ee that the zFil
82a0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
82b0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
82c0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
82d0: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
82e0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
82f0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e  xFullPathname().
8300: 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72    SQLite further
8310: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
8320: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
8330: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
8340: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
8350: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
8360: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
8370: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
8380: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
8390: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
83a0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
83b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
83c0: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
83d0: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
83e0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
83f0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
8400: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
8410: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
8420: 72 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20  r is xOpen is a 
8430: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
8440: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
8450: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
8460: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
8470: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65  r the file.  Whe
8480: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
8490: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
84a0: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
84b0: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
84c0: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
84d0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
84e0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
84f0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
8500: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
8510: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8520: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
8530: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
8540: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
8550: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
8560: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8570: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
8580: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
8590: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
85a0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
85b0: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
85c0: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
85d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
85e0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
85f0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
8600: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
8610: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
8620: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
8630: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
8640: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
8650: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
8660: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
8670: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
8680: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  be set..**.** SQ
8690: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
86a0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
86b0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
86c0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
86d0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
86e0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
86f0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
8700: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
8710: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
8720: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
8730: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8740: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
8750: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8760: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
8770: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8780: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
8790: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
87a0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
87b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
87c0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
87d0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
87e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
87f0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
8800: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  >.**.** The file
8810: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
8820: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
8830: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
8840: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
8850: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
8860: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
8870: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
8880: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
8890: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
88a0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
88b0: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
88c0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
88d0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
88e0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
88f0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
8900: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
8910: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
8920: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
8930: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
8940: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
8950: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
8960: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
8970: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
8980: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
8990: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
89a0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
89b0: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
89c0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
89d0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
89e0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
89f0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
8a00: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
8a10: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
8a20: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
8a30: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8a40: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8a50: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
8a60: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8a70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8a80: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8a90: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8aa0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
8ab0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8ac0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8ad0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
8ae0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
8af0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
8b00: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
8b10: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65   is closed.  The
8b20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8b30: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
8b40: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
8b50: 54 45 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c  TEMP  databases,
8b60: 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f   journals and fo
8b70: 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  r subjournals..*
8b80: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8b90: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
8ba0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
8bb0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
8bc0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
8bd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
8be0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
8bf0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
8c00: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
8c10: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
8c20: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
8c30: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
8c40: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
8c50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
8c60: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
8c70: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
8c80: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
8c90: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
8ca0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8cb0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
8cc0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
8cd0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
8ce0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
8cf0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
8d00: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
8d10: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
8d20: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
8d30: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
8d40: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
8d50: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
8d60: 2a 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46  * At least szOsF
8d70: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
8d80: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
8d90: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
8da0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
8db0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
8dc0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
8dd0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
8de0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
8df0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
8e00: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
8e10: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
8e20: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
8e30: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
8e40: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
8e50: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
8e60: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
8e70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
8e80: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
8e90: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
8ea0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8eb0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
8ec0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
8ed0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
8ee0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
8ef0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
8f00: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
8f10: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
8f20: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
8f30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
8f40: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
8f50: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
8f60: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
8f70: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
8f80: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
8f90: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
8fa0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
8fb0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
8fc0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
8fd0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
8fe0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
8ff0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
9000: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9010: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
9020: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
9030: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
9040: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
9050: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9060: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
9070: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
9080: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
9090: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
90a0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
90b0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ry..**.** SQLite
90c0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
90d0: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
90e0: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
90f0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
9100: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
9110: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
9120: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
9130: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
9140: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
9150: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
9160: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
9170: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
9180: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
9190: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
91a0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
91b0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
91c0: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
91d0: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
91e0: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
91f0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
9200: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
9210: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
9220: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
9230: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
9240: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
9250: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
9260: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
9270: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
9280: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
9290: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
92a0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
92b0: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
92c0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
92d0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
92e0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
92f0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
9300: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
9310: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
9320: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
9330: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
9340: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
9350: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
9360: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
9370: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
9380: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
9390: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
93a0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
93b0: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
93c0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
93d0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
93e0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
93f0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
9400: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
9410: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
9420: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
9430: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74  n.  The xCurrent
9440: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
9450: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
9460: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
9470: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
9480: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  e and time..**.*
9490: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
94a0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
94b0: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74  ite3_vfs;.struct
94c0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
94d0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
94e0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
94f0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
9500: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
9510: 20 32 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   2) */.  int szO
9520: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
9530: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
9540: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
9550: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
9560: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
9570: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
9580: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
9590: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
95a0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
95b0: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
95c0: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
95d0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
95e0: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
95f0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
9600: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
9610: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
9620: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
9630: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
9640: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
9650: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
9660: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9670: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
9680: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
9690: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
96a0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
96b0: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
96c0: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
96d0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
96e0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
96f0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
9700: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
9710: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
9720: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
9730: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
9740: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
9750: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
9760: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9770: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
9780: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
9790: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
97a0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
97b0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
97c0: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
97d0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
97e0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
97f0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
9800: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
9810: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
9820: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
9830: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
9840: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
9850: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
9860: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
9870: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
9880: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
9890: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
98a0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
98b0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
98c0: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
98d0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
98e0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
98f0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
9900: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
9910: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
9920: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
9930: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
9940: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
9950: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
9960: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
9970: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
9980: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
9990: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
99a0: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
99b0: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
99c0: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
99d0: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  .  */.  int (*xR
99e0: 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  ename)(sqlite3_v
99f0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9a00: 2a 7a 4f 6c 64 2c 20 63 6f 6e 73 74 20 63 68 61  *zOld, const cha
9a10: 72 20 2a 7a 4e 65 77 2c 20 69 6e 74 20 64 69 72  r *zNew, int dir
9a20: 53 79 6e 63 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Sync);.  int (*x
9a30: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
9a40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9a50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
9a60: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
9a70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
9a80: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
9a90: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
9aa0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
9ab0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
9ac0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
9ad0: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
9ae0: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
9af0: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
9b00: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
9b10: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
9b20: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
9b30: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
9b40: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
9b50: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
9b60: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
9b70: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
9b80: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
9b90: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
9ba0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
9bb0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
9bc0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
9bd0: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
9be0: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
9bf0: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
9c00: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
9c10: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
9c20: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
9c30: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
9c40: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
9c50: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
9c60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9c70: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
9c80: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
9c90: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
9ca0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
9cb0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
9cc0: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62  er the file is b
9cd0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
9ce0: 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69   writable..** Wi
9cf0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
9d00: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
9d10: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
9d20: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9d30: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
9d40: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
9d50: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
9d60: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
9d70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9d80: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
9d90: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9da0: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
9db0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
9dc0: 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
9dd0: 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
9de0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
9df0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
9e00: 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
9e10: 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
9e20: 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
9e30: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
9e40: 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
9e50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
9e60: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
9e70: 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
9e80: 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
9e90: 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
9ea0: 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
9eb0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
9ec0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
9ed0: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
9ee0: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
9ef0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
9f00: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
9f10: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
9f20: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
9f30: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
9f40: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
9f50: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
9f60: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
9f70: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
9f80: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
9f90: 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
9fa0: 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
9fb0: 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
9fc0: 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
9fd0: 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f  .** was given no
9fe0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
9ff0: 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
a000: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
a010: 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
a020: 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
a030: 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
a040: 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
a050: 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
a060: 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
a070: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
a080: 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
a090: 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
a0a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a0b0: 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
a0c0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
a0d0: 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
a0e0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
a0f0: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
a100: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
a110: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
a120: 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
a130: 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
a140: 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
a150: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
a160: 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
a170: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a180: 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
a190: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
a1a0: 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
a1b0: 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
a1c0: 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
a1d0: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
a1e0: 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
a1f0: 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
a200: 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
a210: 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
a220: 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
a230: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
a240: 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
a250: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a260: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
a270: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
a280: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
a290: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
a2a0: 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
a2b0: 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
a2c0: 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
a2d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a2e0: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
a2f0: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
a300: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
a310: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
a320: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a330: 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
a340: 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
a350: 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
a360: 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
a370: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
a380: 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
a390: 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
a3a0: 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
a3b0: 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
a3c0: 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
a3d0: 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
a3e0: 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
a3f0: 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
a400: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
a410: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a420: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
a430: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
a440: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
a450: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
a460: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
a470: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
a480: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
a490: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
a4a0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
a4b0: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
a4c0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
a4d0: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
a4e0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
a4f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
a500: 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
a510: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
a520: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a530: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
a540: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
a550: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
a560: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
a570: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
a580: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
a590: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
a5a0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
a5b0: 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
a5c0: 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
a5d0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a5e0: 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
a5f0: 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
a600: 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
a610: 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
a620: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
a630: 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
a640: 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
a650: 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
a660: 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
a670: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
a680: 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
a690: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
a6a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
a6b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
a6c0: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
a6d0: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
a6e0: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
a6f0: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
a700: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
a710: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
a720: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
a730: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
a740: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
a750: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
a760: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
a770: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
a780: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
a790: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
a7a0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
a7b0: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
a7c0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a7d0: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
a7e0: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
a7f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a800: 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
a810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
a820: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
a830: 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
a840: 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
a850: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
a860: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
a870: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
a880: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
a890: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a8a0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
a8b0: 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
a8c0: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
a8d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
a8e0: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
a8f0: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
a900: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
a910: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
a920: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
a930: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
a940: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
a950: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
a960: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
a970: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
a980: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
a990: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
a9a0: 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
a9b0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
a9c0: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
a9d0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
a9e0: 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
a9f0: 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
aa00: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
aa10: 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
aa20: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
aa30: 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
aa40: 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
aa50: 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
aa60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
aa70: 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
aa80: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
aa90: 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
aaa0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
aab0: 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
aac0: 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
aad0: 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
aae0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
aaf0: 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
ab00: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
ab10: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
ab20: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
ab30: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
ab40: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ab50: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
ab60: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
ab70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ab80: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
ab90: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
aba0: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
abb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
abc0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
abd0: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
abe0: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
abf0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
ac00: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
ac10: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
ac20: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
ac30: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
ac40: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
ac50: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
ac60: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
ac70: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
ac80: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
ac90: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
aca0: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
acb0: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
acc0: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
acd0: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
ace0: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
acf0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
ad00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
ad10: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
ad20: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
ad30: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
ad40: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
ad50: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
ad60: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
ad70: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
ad80: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
ad90: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
ada0: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
adb0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
adc0: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
add0: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
ade0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
adf0: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
ae00: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
ae10: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ae20: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
ae30: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
ae40: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
ae50: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
ae60: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
ae70: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
ae80: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
ae90: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
aea0: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
aeb0: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
aec0: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
aed0: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
aee0: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
aef0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
af00: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
af10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
af20: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
af30: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
af40: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
af50: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
af60: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
af70: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
af80: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
af90: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
afa0: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
afb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
afc0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
afd0: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
afe0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
aff0: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
b000: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
b010: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
b020: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
b030: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
b040: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
b050: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
b060: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
b070: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
b080: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
b090: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
b0a0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
b0b0: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
b0c0: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
b0d0: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
b0e0: 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
b0f0: 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
b100: 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
b110: 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
b120: 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
b130: 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
b140: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
b150: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
b160: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
b170: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
b180: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
b190: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
b1a0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
b1b0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
b1c0: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
b1d0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
b1e0: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
b1f0: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
b200: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
b210: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
b220: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
b230: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
b240: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
b250: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
b260: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
b270: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
b280: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
b290: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
b2a0: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
b2b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  int sqlite3_os_i
b2c0: 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nit(void);.int s
b2d0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
b2e0: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
b2f0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
b300: 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
b310: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
b320: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
b330: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
b340: 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
b350: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
b360: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
b370: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
b380: 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
b390: 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
b3a0: 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
b3b0: 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
b3c0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
b3d0: 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
b3e0: 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
b3f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
b400: 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
b410: 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
b420: 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
b430: 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
b440: 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
b450: 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
b460: 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
b470: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
b480: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
b490: 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
b4a0: 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
b4b0: 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
b4c0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
b4d0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
b4e0: 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
b4f0: 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
b500: 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
b510: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
b520: 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
b530: 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
b540: 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
b550: 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
b560: 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
b570: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
b580: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
b590: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
b5a0: 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
b5b0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
b5c0: 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
b5d0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b5e0: 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
b5f0: 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
b600: 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
b610: 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
b620: 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
b630: 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
b640: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
b650: 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
b660: 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
b670: 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
b680: 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
b690: 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
b6a0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
b6b0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
b6c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
b6d0: 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
b6e0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
b6f0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
b700: 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
b710: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
b720: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
b730: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
b740: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
b750: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
b760: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
b770: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
b780: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
b790: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
b7a0: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
b7b0: 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  on the [SQLITE_C
b7c0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
b7d0: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
b7e0: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
b7f0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
b800: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
b810: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
b820: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
b830: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b840: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
b850: 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
b860: 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
b870: 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
b880: 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
b890: 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
b8a0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
b8b0: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
b8c0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
b8d0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
b8e0: 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a  nfig(int, ...);.
b8f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b900: 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62   Configure datab
b910: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
b920: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
b930: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
b940: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
b950: 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
b960: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
b970: 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
b980: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
b990: 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
b9a0: 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
b9b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
b9c0: 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
b9d0: 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
b9e0: 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
b9f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ba00: 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
ba10: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
ba20: 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73 71  ent).  The.** sq
ba30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
ba40: 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  ) interface shou
ba50: 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ld only be used 
ba60: 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
ba70: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
ba80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
ba90: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
baa0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a  qlite3_open()],.
bab0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
bac0: 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  16()], or [sqlit
bad0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
bae0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
baf0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
bb00: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
bb10: 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
bb20: 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
bb30: 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65  n verb - an inte
bb40: 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e  ger code that in
bb50: 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20  dicates what.** 
bb60: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
bb70: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bb80: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
bb90: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20  figured..** The 
bba0: 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20  only choice for 
bbb0: 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53  this value is [S
bbc0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
bbd0: 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65  OOKASIDE]..** Ne
bbe0: 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65  w verbs are like
bbf0: 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69  ly to be added i
bc00: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
bc10: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
bc20: 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  Additional argum
bc30: 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74  ents depend on t
bc40: 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  he verb..**.** ^
bc50: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
bc60: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
bc70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
bc80: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
bc90: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
bca0: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
bcb0: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
bcc0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
bcd0: 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
bce0: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
bcf0: 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
bd00: 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
bd10: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
bd20: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
bd30: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
bd40: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
bd50: 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
bd60: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
bd70: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
bd80: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
bd90: 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
bda0: 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
bdb0: 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
bdc0: 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
bdd0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
bde0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
bdf0: 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
be00: 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
be10: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
be20: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
be30: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
be40: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
be50: 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
be60: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
be70: 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
be80: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
be90: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
bea0: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
beb0: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
bec0: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
bed0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
bee0: 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
bef0: 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
bf00: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
bf10: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
bf20: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
bf30: 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
bf40: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
bf50: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
bf60: 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
bf70: 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
bf80: 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
bf90: 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
bfa0: 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
bfb0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
bfc0: 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
bfd0: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
bfe0: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
bff0: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
c000: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
c010: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
c020: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
c030: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
c040: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
c050: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
c060: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
c070: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c080: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
c090: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
c0a0: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
c0b0: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
c0c0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
c0d0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
c0e0: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
c0f0: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
c100: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
c110: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
c120: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
c130: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
c140: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
c150: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
c160: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
c170: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
c180: 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46  e xMalloc and xF
c190: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
c1a0: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
c1b0: 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  * malloc() and f
c1c0: 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
c1d0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
c1e0: 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
c1f0: 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74  The xRealloc met
c200: 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  hod must work li
c210: 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f  ke realloc() fro
c220: 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
c230: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68   library.** with
c240: 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74   the exception t
c250: 68 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e  hat if the secon
c260: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52  d argument to xR
c270: 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a  ealloc is zero,.
c280: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74  ** xRealloc must
c290: 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74   be a no-op - it
c2a0: 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72   must not perfor
c2b0: 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  m any allocation
c2c0: 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74   or.** deallocat
c2d0: 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67 75  ion.  ^SQLite gu
c2e0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
c2f0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
c300: 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
c310: 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
c320: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
c330: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
c340: 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20  Roundup..** And 
c350: 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72  so in cases wher
c360: 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79  e xRoundup alway
c370: 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69  s returns a posi
c380: 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20  tive number,.** 
c390: 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72  xRealloc can per
c3a0: 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20  form exactly as 
c3b0: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62  the standard lib
c3c0: 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61  rary realloc() a
c3d0: 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69  nd.** still be i
c3e0: 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74  n compliance wit
c3f0: 68 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61  h this specifica
c400: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  tion..**.** xSiz
c410: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
c420: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
c430: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
c440: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
c450: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
c460: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
c470: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
c480: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
c490: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
c4a0: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
c4b0: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
c4c0: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
c4d0: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
c4e0: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
c4f0: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
c500: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
c510: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
c520: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c530: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
c540: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
c550: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
c560: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
c570: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
c580: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
c590: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
c5a0: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
c5b0: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
c5c0: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
c5d0: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
c5e0: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
c5f0: 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
c600: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c610: 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
c620: 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
c630: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
c640: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
c650: 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
c660: 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
c670: 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
c680: 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
c690: 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
c6a0: 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
c6b0: 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
c6c0: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
c6d0: 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
c6e0: 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
c6f0: 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f   allocator.  (Fo
c700: 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
c710: 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
c720: 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
c730: 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
c740: 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
c750: 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
c760: 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
c770: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
c780: 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
c790: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
c7a0: 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
c7b0: 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
c7c0: 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
c7d0: 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
c7e0: 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
c7f0: 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
c800: 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
c810: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
c820: 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
c830: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
c840: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
c850: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
c860: 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
c870: 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
c880: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
c890: 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
c8a0: 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
c8b0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
c8c0: 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
c8d0: 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
c8e0: 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
c8f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
c900: 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
c910: 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
c920: 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
c930: 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
c940: 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
c950: 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
c960: 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
c970: 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
c980: 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
c990: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
c9a0: 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
c9b0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
c9c0: 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
c9d0: 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
c9e0: 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
c9f0: 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
ca00: 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
ca10: 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
ca20: 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
ca30: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
ca40: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
ca50: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
ca60: 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
ca70: 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
ca80: 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
ca90: 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
caa0: 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
cab0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
cac0: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
cad0: 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
cae0: 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
caf0: 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
cb00: 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
cb10: 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
cb20: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
cb30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
cb40: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
cb50: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
cb60: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
cb70: 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
cb80: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
cb90: 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
cba0: 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
cbb0: 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
cbc0: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
cbd0: 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
cbe0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
cbf0: 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
cc00: 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
cc10: 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
cc20: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
cc30: 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
cc40: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
cc50: 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
cc60: 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
cc70: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
cc80: 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
cc90: 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
cca0: 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
ccb0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
ccc0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
ccd0: 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
cce0: 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
ccf0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
cd00: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
cd10: 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
cd20: 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
cd30: 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
cd40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
cd50: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
cd60: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
cd70: 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
cd80: 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
cd90: 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
cda0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
cdb0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
cdc0: 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
cdd0: 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
cde0: 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
cdf0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
ce00: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
ce10: 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
ce20: 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
ce30: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
ce40: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
ce50: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
ce60: 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
ce70: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
ce80: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
ce90: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
cea0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
ceb0: 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
cec0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
ced0: 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
cee0: 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
cef0: 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
cf00: 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
cf10: 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
cf20: 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
cf30: 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
cf40: 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
cf50: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
cf60: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
cf70: 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
cf80: 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
cf90: 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
cfa0: 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
cfb0: 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
cfc0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
cfd0: 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
cfe0: 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
cff0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
d000: 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
d010: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
d020: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
d030: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
d040: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
d050: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
d060: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
d070: 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
d080: 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
d090: 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
d0a0: 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
d0b0: 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
d0c0: 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
d0d0: 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
d0e0: 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
d0f0: 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
d100: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
d110: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
d120: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
d130: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
d140: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
d150: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
d160: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
d170: 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
d180: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d190: 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
d1a0: 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
d1b0: 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
d1c0: 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
d1d0: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
d1e0: 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
d1f0: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
d200: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
d210: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
d220: 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
d230: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
d240: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d250: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
d260: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
d270: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
d280: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
d290: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
d2a0: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
d2b0: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
d2c0: 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
d2d0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
d2e0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
d2f0: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
d300: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d310: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
d320: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d330: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
d340: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
d350: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
d360: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
d370: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
d380: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
d390: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
d3a0: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
d3b0: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
d3c0: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
d3d0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
d3e0: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
d3f0: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
d400: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
d410: 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
d420: 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
d430: 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
d440: 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
d450: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
d460: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
d470: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
d480: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
d490: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
d4a0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
d4b0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
d4c0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
d4d0: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
d4e0: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
d4f0: 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
d500: 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
d510: 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
d520: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
d530: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
d540: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
d550: 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
d560: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
d570: 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
d580: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
d590: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d5a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
d5b0: 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
d5c0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
d5d0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
d5e0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
d5f0: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
d600: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
d610: 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
d620: 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
d630: 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
d640: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
d650: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
d660: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
d670: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
d680: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d690: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
d6a0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
d6b0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
d6c0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
d6d0: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
d6e0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
d6f0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
d700: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
d710: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
d720: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
d730: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
d740: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
d750: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
d760: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d770: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
d780: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
d790: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
d7a0: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
d7b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
d7c0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
d7d0: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
d7e0: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
d7f0: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
d800: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
d810: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d820: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d830: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d840: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d850: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d860: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d870: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d880: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d890: 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
d8a0: 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
d8b0: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
d8c0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
d8d0: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
d8e0: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
d8f0: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
d900: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
d910: 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
d920: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
d930: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d940: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
d950: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
d960: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
d970: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
d980: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
d990: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
d9a0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
d9b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
d9c0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
d9d0: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
d9e0: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
d9f0: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
da00: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
da10: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
da20: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
da30: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
da40: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
da50: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
da60: 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
da70: 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
da80: 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
da90: 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
daa0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
dab0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
dac0: 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
dad0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
dae0: 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
daf0: 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
db00: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
db10: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
db20: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
db30: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
db40: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
db50: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
db60: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
db70: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
db80: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
db90: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
dba0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
dbb0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
dbc0: 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
dbd0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
dbe0: 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
dbf0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
dc00: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
dc10: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
dc20: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
dc30: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
dc40: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
dc50: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
dc60: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
dc70: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
dc80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
dc90: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
dca0: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
dcb0: 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
dcc0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
dcd0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
dce0: 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
dcf0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
dd00: 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
dd10: 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
dd20: 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
dd30: 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77  a .** boolean, w
dd40: 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
dd50: 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
dd60: 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
dd70: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a  y allocation .**
dd80: 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
dd90: 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
dda0: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
ddb0: 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74   are disabled, t
ddc0: 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  he .** following
ddd0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
dde0: 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
ddf0: 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
de00: 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
de10: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
de20: 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
de30: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
de40: 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
de50: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
de60: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
de70: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
de80: 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
de90: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
dea0: 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
deb0: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
dec0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
ded0: 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
dee0: 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
def0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
df00: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
df10: 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
df20: 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
df30: 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
df40: 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
df50: 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
df60: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
df70: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
df80: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
df90: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
dfa0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
dfb0: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
dfc0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
dfd0: 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
dfe0: 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
dff0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
e000: 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
e010: 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
e020: 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
e030: 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
e040: 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63  the scrach alloc
e050: 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
e060: 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
e070: 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
e080: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
e090: 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
e0a0: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
e0b0: 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
e0c0: 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a  ons (N).  The sz
e0d0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  .** argument mus
e0e0: 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20  t be a multiple 
e0f0: 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61  of 16. The sz pa
e100: 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
e110: 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a  e a few bytes.**
e120: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
e130: 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68 20   actual scratch 
e140: 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 64  space required d
e150: 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20 6f  ue to internal o
e160: 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65 20  verhead..** The 
e170: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
e180: 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72  ust be a pointer
e190: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
e1a0: 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20  igned buffer.** 
e1b0: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
e1c0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
e1d0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
e1e0: 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68  l use no more th
e1f0: 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
e200: 75 66 66 65 72 20 70 65 72 20 74 68 72 65 61 64  uffer per thread
e210: 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
e220: 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20  d be set to the 
e230: 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
e240: 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
e250: 64 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  ds.  ^SQLite wil
e260: 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71 75 69  l.** never requi
e270: 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
e280: 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
e290: 20 74 68 61 6e 20 36 20 74 69 6d 65 73 20 74 68   than 6 times th
e2a0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70 61  e database.** pa
e2b0: 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
e2c0: 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
e2d0: 61 64 64 69 74 69 6f 6e 61 6c 20 73 63 72 61 74  additional scrat
e2e0: 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
e2f0: 20 0a 2a 2a 20 77 68 61 74 20 69 73 20 70 72 6f   .** what is pro
e300: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
e310: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e320: 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
e330: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
e340: 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
e350: 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
e360: 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a  y needed.</dd>.*
e370: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e380: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
e390: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
e3a0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
e3b0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
e3c0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
e3d0: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
e3e0: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
e3f0: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
e400: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
e410: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
e420: 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  menation.  .** T
e430: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
e440: 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
e450: 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
e460: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
e470: 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
e480: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
e490: 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
e4a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
e4b0: 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  CHE option..** T
e4c0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
e4d0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
e4e0: 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
e4f0: 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
e500: 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
e510: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
e520: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
e530: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
e540: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
e550: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
e560: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
e570: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
e580: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
e590: 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
e5a0: 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
e5b0: 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
e5c0: 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
e5d0: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
e5e0: 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
e5f0: 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
e600: 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
e610: 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
e620: 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
e630: 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
e640: 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
e650: 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
e660: 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
e670: 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
e680: 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
e690: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
e6a0: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
e6b0: 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
e6c0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
e6d0: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
e6e0: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
e6f0: 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
e700: 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
e710: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e720: 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
e730: 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
e740: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
e750: 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
e760: 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
e770: 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
e780: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
e790: 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
e7a0: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
e7b0: 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
e7c0: 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
e7d0: 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
e7e0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
e7f0: 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
e800: 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
e810: 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ** ^The implemen
e820: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65  tation might use
e830: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
e840: 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f  the N buffers to
e850: 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79   hold .** memory
e860: 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f   accounting info
e870: 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f 69  rmation. The poi
e880: 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  nter in the firs
e890: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a  t argument must.
e8a0: 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  ** be aligned to
e8b0: 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64   an 8-byte bound
e8c0: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
e8d0: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
e8e0: 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  Lite.** will be 
e8f0: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
e900: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e910: 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
e920: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
e930: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e940: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e950: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e960: 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
e970: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
e980: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
e990: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
e9a0: 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
e9b0: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
e9c0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
e9d0: 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
e9e0: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
e9f0: 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
ea00: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
ea10: 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  ts: An 8-byte al
ea20: 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
ea30: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
ea40: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
ea50: 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
ea60: 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
ea70: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
ea80: 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
ea90: 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
eaa0: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
eab0: 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
eac0: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
ead0: 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
eae0: 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
eaf0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
eb00: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
eb10: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
eb20: 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
eb30: 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
eb40: 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
eb50: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
eb60: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
eb70: 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
eb80: 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
eb90: 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
eba0: 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
ebb0: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
ebc0: 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
ebd0: 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
ebe0: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ebf0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
ec00: 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
ec10: 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
ec20: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
ec30: 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
ec40: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
ec50: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
ec60: 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
ec70: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
ec80: 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
ec90: 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
eca0: 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
ecb0: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
ecc0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ecd0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
ece0: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
ecf0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
ed00: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
ed10: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
ed20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
ed30: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
ed40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
ed50: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
ed60: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
ed70: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
ed80: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
ed90: 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
eda0: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
edb0: 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
edc0: 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
edd0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
ede0: 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
edf0: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
ee00: 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
ee10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
ee20: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
ee30: 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
ee40: 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
ee50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ee60: 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
ee70: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
ee80: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
ee90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
eea0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
eeb0: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
eec0: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
eed0: 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
eee0: 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
eef0: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
ef00: 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
ef10: 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
ef20: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ef30: 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
ef40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
ef50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ef60: 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
ef70: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
ef80: 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  R].</dd>.**.** <
ef90: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
efa0: 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
efb0: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
efc0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
efd0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
efe0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
eff0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
f000: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
f010: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
f020: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
f030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
f040: 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
f050: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
f060: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
f070: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
f080: 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
f090: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
f0a0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
f0b0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
f0c0: 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
f0d0: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
f0e0: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
f0f0: 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
f100: 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
f110: 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
f120: 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
f130: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
f140: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
f150: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
f160: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
f170: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
f180: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
f190: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
f1a0: 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
f1b0: 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
f1c0: 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
f1d0: 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
f1e0: 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
f1f0: 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
f200: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
f210: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
f220: 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
f230: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
f240: 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
f250: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
f260: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
f270: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
f280: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
f290: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
f2a0: 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
f2b0: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
f2c0: 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
f2d0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
f2e0: 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f  tion for the loo
f2f0: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
f300: 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a  locator on each.
f310: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
f320: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66  nection].  The f
f330: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
f340: 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
f350: 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
f360: 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
f370: 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
f380: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
f390: 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
f3a0: 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
f3b0: 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
f3c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
f3d0: 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75   the.** <i>defau
f3e0: 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
f3f0: 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
f400: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f410: 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74  ASIDE].** verb t
f420: 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
f430: 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
f440: 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
f450: 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
f460: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
f470: 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
f480: 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
f490: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
f4a0: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f  _CONFIG_PCACHE</
f4b0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
f4c0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f4d0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
f4e0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
f4f0: 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
f500: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
f510: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
f520: 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
f530: 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
f540: 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
f550: 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
f560: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
f570: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
f580: 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
f590: 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
f5a0: 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
f5b0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
f5c0: 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
f5d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f5e0: 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74  IG_GETPCACHE</dt
f5f0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
f600: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
f610: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
f620: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
f630: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
f640: 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
f650: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ods] object.  SQ
f660: 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
f670: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
f680: 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
f690: 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
f6a0: 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
f6b0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f6c0: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
f6d0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
f6e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
f6f0: 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
f700: 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
f710: 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
f720: 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
f730: 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
f740: 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
f750: 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
f760: 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
f770: 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
f780: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
f790: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
f7a0: 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
f7b0: 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
f7c0: 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
f7d0: 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
f7e0: 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
f7f0: 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
f800: 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
f810: 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
f820: 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
f830: 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
f840: 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
f850: 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
f860: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
f870: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
f880: 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
f890: 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
f8a0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
f8b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
f8c0: 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
f8d0: 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
f8e0: 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
f8f0: 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
f900: 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
f910: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
f920: 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
f930: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
f940: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
f950: 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
f960: 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
f970: 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
f980: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
f990: 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
f9a0: 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
f9b0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
f9c0: 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
f9d0: 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
f9e0: 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
f9f0: 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
fa00: 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
fa10: 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
fa20: 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
fa30: 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
fa40: 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
fa50: 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
fa60: 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
fa70: 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
fa80: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fa90: 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
faa0: 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
fab0: 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
fac0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
fad0: 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
fae0: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
faf0: 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
fb00: 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
fb10: 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
fb20: 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
fb30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
fb40: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
fb50: 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
fb60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
fb70: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
fb80: 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
fb90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fba0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
fbb0: 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
fbc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fbd0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
fbe0: 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
fbf0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
fc00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
fc10: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
fc20: 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
fc30: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fc40: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
fc50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
fc60: 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
fc70: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
fc80: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
fc90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
fca0: 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
fcb0: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
fcc0: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
fcd0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fce0: 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
fcf0: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
fd00: 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
fd10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fd20: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
fd30: 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
fd40: 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
fd50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
fd60: 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
fd70: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
fd80: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
fd90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
fda0: 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
fdb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
fdc0: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
fdd0: 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
fde0: 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
fdf0: 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
fe00: 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
fe10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fe20: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
fe30: 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
fe40: 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
fe50: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
fe60: 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
fe70: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
fe80: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
fe90: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
fea0: 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
feb0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
fec0: 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
fed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
fee0: 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
fef0: 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
ff00: 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   void* */../*.**
ff10: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
ff20: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
ff30: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
ff40: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
ff50: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
ff60: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
ff70: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
ff80: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
ff90: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
ffa0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
ffb0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
ffc0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
ffd0: 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
ffe0: 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
fff0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10000 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10010 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10020 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10030 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
10040 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
10050 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
10060 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
10070 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
10080 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
10090 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
100a0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
100b0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
100c0 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
100d0 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
100e0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
100f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
10100 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
10110 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
10120 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
10130 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
10140 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10150 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
10160 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
10170 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
10180 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10190 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
101a0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
101b0 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
101c0 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
101d0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
101e0 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
101f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
10200 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
10210 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
10220 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
10230 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
10240 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
10250 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
10260 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10270 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
10280 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62  r to an memory b
10290 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
102a0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
102b0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
102c0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
102d0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
102e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
102f0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
10300 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
10310 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
10320 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
10330 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
10340 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
10350 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
10360 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10370 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
10380 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
10390 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
103a0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
103b0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
103c0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
103d0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
103e0 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
103f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
10400 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
10410 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
10420 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
10430 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
10440 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
10450 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
10460 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
10470 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
10480 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
10490 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
104a0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
104b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
104c0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
104d0 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
104e0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
104f0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
10500 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a   next smaller.**
10510 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
10520 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
10530 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
10540 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  IDE]</dd>.**.** 
10550 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
10560 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
10570 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30  _LOOKASIDE    10
10580 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
10590 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20   int */.../*.** 
105a0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
105b0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
105c0 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
105d0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
105e0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
105f0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
10600 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
10610 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
10620 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
10630 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
10640 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
10650 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
10660 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
10670 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
10680 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
10690 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
106a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
106b0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
106c0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
106d0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
106e0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
106f0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
10700 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
10710 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
10720 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
10730 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
10740 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
10750 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
10760 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
10770 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
10780 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
10790 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
107a0 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
107b0 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
107c0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
107d0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
107e0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
107f0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
10800 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
10810 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
10820 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
10830 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
10840 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
10850 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
10860 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
10870 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
10880 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
10890 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
108a0 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
108b0 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
108c0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
108d0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
108e0 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
108f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
10900 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10910 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e  argument.  ^If n
10920 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
10930 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65  SERT]s.** have e
10940 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20  ver occurred on 
10950 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f  that database co
10960 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69  nnection, zero i
10970 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
10980 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
10990 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
109a0 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
109b0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
109c0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
109d0 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
109e0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
109f0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
10a00 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
10a10 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
10a20 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
10a30 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
10a40 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
10a50 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
10a60 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
10a70 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
10a80 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
10a90 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  er fired.)^.**.*
10aa0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
10ab0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
10ac0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
10ad0 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
10ae0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
10af0 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
10b00 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
10b10 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10b20 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
10b30 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
10b40 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
10b50 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
10b60 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
10b70 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
10b80 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
10b90 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
10ba0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
10bb0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
10bc0 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
10bd0 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
10be0 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
10bf0 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
10c00 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
10c10 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
10c20 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
10c30 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
10c40 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
10c50 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
10c60 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
10c70 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
10c80 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
10c90 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
10ca0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
10cb0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
10cc0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
10cd0 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
10ce0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
10cf0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
10d00 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
10d10 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
10d20 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
10d30 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
10d40 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
10d50 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
10d60 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
10d70 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
10d80 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
10d90 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
10da0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
10db0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
10dc0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
10dd0 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
10de0 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
10df0 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
10e00 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
10e10 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
10e20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
10e30 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
10e40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
10e50 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
10e60 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
10e70 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
10e80 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
10e90 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
10ea0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
10eb0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
10ec0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
10ed0 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
10ee0 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
10ef0 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
10f00 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
10f10 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
10f20 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
10f30 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
10f40 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
10f50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
10f60 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
10f70 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
10f80 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
10f90 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
10fa0 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73  umber of databas
10fb0 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65  e rows that were
10fc0 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69   changed.** or i
10fd0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
10fe0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
10ff0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
11000 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  d SQL statement.
11010 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ** on the [datab
11020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11030 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
11040 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11050 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e  ..** ^(Only chan
11060 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
11070 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
11080 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
11090 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
110a0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
110b0 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
110c0 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
110d0 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
110e0 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
110f0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
11100 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
11110 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a  ed.)^ Use the.**
11120 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
11130 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
11140 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ion to find the 
11150 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  total number of 
11160 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75  changes.** inclu
11170 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
11180 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20  sed by triggers 
11190 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20  and foreign key 
111a0 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  actions..**.** ^
111b0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
111c0 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c  w that are simul
111d0 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54  ated by an [INST
111e0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a  EAD OF trigger].
111f0 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  ** are not count
11200 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74  ed.  Only real t
11210 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65  able changes are
11220 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
11230 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  ^(A "row change"
11240 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
11250 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
11260 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
11270 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
11280 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
11290 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
112a0 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
112b0 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
112c0 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
112d0 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
112e0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
112f0 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41  ,.** rollback, A
11300 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
11310 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f   [DROP TABLE], o
11320 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a  r by any other.*
11330 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20  * mechanisms do 
11340 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72  not count as dir
11350 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e  ect row changes.
11360 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67  )^.**.** A "trig
11370 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20  ger context" is 
11380 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75  a scope of execu
11390 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73  tion that begins
113a0 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74   and.** ends wit
113b0 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20  h the script of 
113c0 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  a [CREATE TRIGGE
113d0 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a  R | trigger]. .*
113e0 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65  * Most SQL state
113f0 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61  ments are.** eva
11400 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f  luated outside o
11410 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20  f any trigger.  
11420 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70  This is the "top
11430 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67   level".** trigg
11440 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20  er context.  If 
11450 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20  a trigger fires 
11460 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
11470 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69  el, a.** new tri
11480 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20  gger context is 
11490 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20  entered for the 
114a0 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74  duration of that
114b0 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e   one.** trigger.
114c0 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72    Subtriggers cr
114d0 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73  eate subcontexts
114e0 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74   for their durat
114f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ion..**.** ^Call
11500 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  ing [sqlite3_exe
11510 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
11520 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69  _step()] recursi
11530 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  vely does.** not
11540 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72   create a new tr
11550 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
11560 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
11570 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
11580 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74  number of direct
11590 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20   row changes in 
115a0 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65  the.** most rece
115b0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
115c0 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  E, or DELETE sta
115d0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
115e0 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65  e same.** trigge
115f0 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
11600 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c   ^Thus, when cal
11610 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  led from the top
11620 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e   level, this fun
11630 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
11640 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
11650 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
11660 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
11670 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
11680 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f  ETE.** that also
11690 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65   occurred at the
116a0 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57   top level.  ^(W
116b0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
116c0 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
116d0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
116e0 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
116f0 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
11700 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
11710 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
11720 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
11730 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
11740 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
11750 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
11760 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
11770 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
11780 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
11790 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
117a0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
117b0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
117c0 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
117d0 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
117e0 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
117f0 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29  ir own context.)
11800 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
11810 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
11820 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
11830 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
11840 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
11850 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
11860 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
11870 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
11880 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
11890 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
118a0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
118b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
118c0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
118d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
118e0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
118f0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
11900 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
11910 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
11920 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
11930 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
11940 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
11950 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
11960 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
11970 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
11980 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
11990 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
119a0 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
119b0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
119c0 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
119d0 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
119e0 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
119f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
11a00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
11a10 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
11a20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
11a30 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
11a40 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
11a50 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
11a60 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
11a70 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
11a80 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
11a90 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
11aa0 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
11ab0 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
11ac0 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
11ad0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
11ae0 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
11af0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
11b00 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
11b10 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
11b20 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
11b30 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
11b40 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
11b50 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
11b60 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
11b70 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
11b80 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
11b90 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
11ba0 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
11bb0 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
11bc0 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
11bd0 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
11be0 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
11bf0 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
11c00 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
11c10 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
11c20 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
11c30 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
11c40 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
11c50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
11c60 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
11c70 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
11c80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
11c90 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
11ca0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
11cb0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
11cc0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
11cd0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
11ce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
11cf0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
11d00 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
11d10 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
11d20 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
11d30 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
11d40 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
11d50 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
11d60 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
11d70 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
11d80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11d90 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
11da0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
11db0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
11dc0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
11dd0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
11de0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
11df0 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
11e00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
11e10 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
11e20 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
11e30 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
11e40 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
11e50 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e  ng Query.**.** ^
11e60 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
11e70 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
11e80 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
11e90 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
11ea0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
11eb0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
11ec0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
11ed0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
11ee0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
11ef0 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
11f00 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
11f10 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
11f20 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
11f30 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
11f40 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
11f50 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
11f60 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
11f70 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
11f80 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
11f90 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
11fa0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
11fb0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
11fc0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
11fd0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
11fe0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
11ff0 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
12000 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
12010 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
12020 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
12030 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12040 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
12050 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
12060 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
12070 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
12080 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
12090 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
120a0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
120b0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
120c0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
120d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
120e0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
120f0 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
12100 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
12110 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
12120 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
12130 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
12140 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
12150 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
12160 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
12170 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
12180 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
12190 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
121a0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
121b0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
121c0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
121d0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
121e0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
121f0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
12200 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
12210 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
12220 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
12230 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
12240 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
12250 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12260 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
12270 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
12280 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
12290 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
122a0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
122b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
122c0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
122d0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
122e0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
122f0 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
12300 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
12310 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
12320 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
12330 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
12340 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
12350 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
12360 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
12370 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
12380 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
12390 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
123a0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
123b0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
123c0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
123d0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
123e0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
123f0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
12400 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
12410 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
12420 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
12430 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
12440 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
12450 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
12460 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
12470 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
12480 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
12490 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
124a0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
124b0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
124c0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
124d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
124e0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
124f0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  turns..**.** If 
12500 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
12510 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77  nection closes w
12520 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e  hile [sqlite3_in
12530 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73  terrupt()].** is
12540 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61   running then ba
12550 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69  d things will li
12560 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a  kely happen..*/.
12570 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
12580 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
12590 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
125a0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
125b0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
125c0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
125d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
125e0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
125f0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
12600 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
12610 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
12620 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
12630 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
12640 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
12650 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
12660 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
12670 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
12680 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
12690 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
126a0 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
126b0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
126c0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
126d0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
126e0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
126f0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
12700 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
12710 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
12720 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
12730 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
12740 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
12750 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
12760 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
12770 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
12780 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
12790 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
127a0 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
127b0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
127c0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
127d0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
127e0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
127f0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
12800 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
12810 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
12820 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
12830 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
12840 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
12850 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
12860 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
12870 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
12880 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
12890 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
128a0 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
128b0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
128c0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
128d0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
128e0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
128f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
12900 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
12910 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
12920 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
12930 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
12940 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
12950 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
12960 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
12970 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
12980 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
12990 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
129a0 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
129b0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
129c0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
129d0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
129e0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
129f0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12a00 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
12a10 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
12a20 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
12a30 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
12a40 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
12a50 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
12a60 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
12a70 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
12a80 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
12a90 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
12aa0 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
12ab0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
12ac0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
12ad0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
12ae0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
12af0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
12b00 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
12b10 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
12b20 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
12b30 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
12b40 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
12b50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
12b60 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
12b70 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
12b80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
12b90 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
12ba0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
12bb0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
12bc0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
12bd0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e  yte order..*/.in
12be0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
12bf0 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
12c00 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ql);.int sqlite3
12c10 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
12c20 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
12c30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
12c40 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
12c50 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
12c60 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
12c70 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
12c80 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
12c90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
12ca0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
12cb0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
12cc0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
12cd0 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
12ce0 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
12cf0 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
12d00 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
12d10 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
12d20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
12d30 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
12d40 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
12d50 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
12d60 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
12d70 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
12d80 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
12d90 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
12da0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
12db0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
12dc0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
12dd0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
12de0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
12df0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
12e00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
12e10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
12e20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
12e30 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
12e40 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
12e50 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
12e60 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
12e70 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
12e80 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
12e90 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
12ea0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
12eb0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
12ec0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
12ed0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
12ee0 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
12ef0 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
12f00 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
12f10 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
12f20 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
12f30 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
12f40 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
12f50 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
12f60 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
12f70 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
12f80 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
12f90 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
12fa0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
12fb0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
12fc0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
12fd0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
12fe0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
12ff0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
13000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
13010 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
13020 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
13030 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
13040 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
13050 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
13060 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
13070 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
13080 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
13090 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
130a0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
130b0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
130c0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
130d0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
130e0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
130f0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
13100 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
13110 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
13120 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
13130 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
13140 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
13150 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
13160 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
13170 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
13180 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
13190 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
131a0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
131b0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
131c0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
131d0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
131e0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
131f0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
13200 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
13210 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
13220 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
13230 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
13240 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
13250 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
13260 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
13270 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
13280 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
13290 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
132a0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
132b0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
132c0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
132d0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
132e0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
132f0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
13300 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
13310 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
13320 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
13330 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
13340 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
13350 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
13360 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
13370 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
13380 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
13390 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
133a0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
133b0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
133c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
133d0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
133e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
133f0 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
13400 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
13410 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
13420 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
13430 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
13440 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
13450 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
13460 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
13470 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
13480 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
13490 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
134a0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
134b0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
134c0 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
134d0 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
134e0 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
134f0 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
13500 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
13510 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
13520 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
13530 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
13540 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
13550 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
13560 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
13570 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
13580 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
13590 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
135a0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
135b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
135c0 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
135d0 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
135e0 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
135f0 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
13600 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
13610 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
13620 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
13630 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
13640 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
13650 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
13660 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
13670 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13680 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
13690 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
136a0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
136b0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
136c0 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
136d0 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
136e0 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
136f0 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
13700 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
13710 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
13720 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
13730 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
13740 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
13750 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
13760 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
13770 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
13780 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
13790 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
137a0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
137b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
137c0 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
137d0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
137e0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
137f0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
13800 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
13810 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
13820 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
13830 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
13840 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
13850 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
13860 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
13870 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
13880 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
13890 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
138a0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
138b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
138c0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
138d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
138e0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
138f0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
13900 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
13910 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
13920 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
13930 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
13940 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13950 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
13960 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
13970 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
13980 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
13990 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
139a0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
139b0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
139c0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
139d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
139e0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
139f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
13a00 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
13a10 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13a20 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
13a30 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
13a40 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
13a50 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
13a60 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
13a70 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
13a80 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
13a90 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
13aa0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
13ab0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
13ac0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
13ad0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
13ae0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
13af0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
13b00 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
13b10 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
13b20 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
13b30 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
13b40 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
13b50 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
13b60 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
13b70 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13b80 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
13b90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
13ba0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
13bb0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
13bc0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
13bd0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
13be0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
13bf0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
13c00 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
13c10 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
13c20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
13c30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13c40 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
13c50 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
13c60 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
13c70 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
13c80 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
13c90 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
13ca0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
13cb0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
13cc0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
13cd0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
13ce0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69   cleared.)^.*/.i
13cf0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
13d00 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
13d10 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
13d20 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
13d30 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
13d40 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
13d50 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ries.**.** Defin
13d60 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
13d70 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
13d80 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
13d90 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
13da0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
13db0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
13dc0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
13dd0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
13de0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
13df0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
13e00 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
13e10 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
13e20 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
13e30 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
13e40 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
13e50 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
13e60 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
13e70 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
13e80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
13e90 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
13ea0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
13eb0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
13ec0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
13ed0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
13ee0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
13ef0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
13f00 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
13f10 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
13f20 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
13f30 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
13f40 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
13f50 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
13f60 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
13f70 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
13f80 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
13f90 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
13fa0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
13fb0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
13fc0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
13fd0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
13fe0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
13ff0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
14000 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
14010 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
14020 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
14030 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
14040 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
14050 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
14060 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
14070 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
14080 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
14090 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
140a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
140b0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
140c0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
140d0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
140e0 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
140f0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
14100 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
14110 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
14120 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
14130 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
14140 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
14150 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
14160 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
14170 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14180 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61  e()]..**.** As a
14190 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
141a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
141b0 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
141c0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
141d0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
141e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
141f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
14200 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
14210 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
14220 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14230 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
14240 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
14250 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
14260 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
14270 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
14280 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
14290 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
142a0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
142b0 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
142c0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
142d0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
142e0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
142f0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
14300 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
14310 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
14320 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
14330 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
14340 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
14350 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
14360 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
14370 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14380 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
14390 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
143a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
143b0 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
143c0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
143d0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
143e0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
143f0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
14400 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
14410 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14420 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
14430 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14440 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
14450 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14460 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
14470 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
14480 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
14490 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
144a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
144b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
144c0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
144d0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
144e0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
144f0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
14500 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
14510 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
14520 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
14530 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
14540 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
14550 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
14560 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
14570 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
14580 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
14590 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
145a0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
145b0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
145c0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
145d0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
145e0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
145f0 73 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20  should pass the 
14600 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
14610 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
14620 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
14630 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
14640 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
14650 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
14660 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
14670 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
14680 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14690 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
146a0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
146b0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
146c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
146d0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
146e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
146f0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
14700 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
14710 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
14720 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
14730 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
14740 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
14750 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
14760 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
14770 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
14780 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
14790 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
147a0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
147b0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
147c0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
147d0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
147e0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
147f0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
14800 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
14810 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
14820 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
14830 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
14840 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
14850 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
14860 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
14870 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
14880 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
14890 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
148a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
148b0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
148c0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
148d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
148e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
148f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
14900 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a  e3_errmsg()].)^.
14910 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  */.int sqlite3_g
14920 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
14930 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
14940 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
14950 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
14960 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
14970 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
14980 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
14990 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
149a0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
149b0 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
149c0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
149d0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
149e0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
149f0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
14a00 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
14a10 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
14a20 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
14a30 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
14a40 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
14a50 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
14a60 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
14a70 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20  here */.);.void 
14a80 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
14a90 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
14aa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14ab0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
14ac0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
14ad0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
14ae0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
14af0 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
14b00 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
14b10 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
14b20 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
14b30 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
14b40 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
14b50 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
14b60 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72  and sqlite3_vmpr
14b70 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20  intf() routines 
14b80 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72  write their.** r
14b90 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f  esults into memo
14ba0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
14bb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14bc0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69  ()]..** The stri
14bd0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
14be0 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e  these two routin
14bf0 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  es should be.** 
14c00 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c  released by [sql
14c10 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e  ite3_free()].  ^
14c20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
14c30 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
14c40 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
14c50 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
14c60 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
14c70 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
14c80 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
14c90 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
14ca0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c  ..**.** ^(In sql
14cb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
14cc0 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
14cd0 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
14ce0 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
14cf0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
14d00 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
14d10 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
14d20 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
14d30 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
14d40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
14d50 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
14d60 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
14d70 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
14d80 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
14d90 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
14da0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
14db0 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
14dc0 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
14dd0 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
14de0 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
14df0 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
14e00 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
14e10 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
14e20 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
14e30 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
14e40 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
14e50 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
14e60 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
14e70 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
14e80 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
14e90 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
14ea0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
14eb0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
14ec0 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
14ed0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
14ee0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
14ef0 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
14f00 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
14f10 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
14f20 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
14f30 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
14f40 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
14f50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
14f60 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
14f70 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
14f80 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
14f90 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
14fa0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
14fb0 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
14fc0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
14fd0 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
14fe0 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
14ff0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
15000 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
15010 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
15020 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
15030 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
15040 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
15050 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
15060 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
15070 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
15080 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
15090 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
150a0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
150b0 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
150c0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
150d0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
150e0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
150f0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
15100 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
15110 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
15120 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
15130 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
15140 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
15150 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
15160 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
15170 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
15180 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
15190 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
151a0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
151b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
151c0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
151d0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
151e0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
151f0 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
15200 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
15210 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
15220 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
15230 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
15240 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
15250 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
15260 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
15270 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
15280 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
15290 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
152a0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
152b0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
152c0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
152d0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
152e0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
152f0 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
15300 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
15310 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
15320 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
15330 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
15340 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15350 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
15360 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
15370 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
15380 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
15390 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
153a0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
153b0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
153c0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
153d0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
153e0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
153f0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
15400 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
15410 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
15420 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
15430 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
15440 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
15450 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
15460 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
15470 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
15480 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
15490 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
154a0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
154b0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
154c0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
154d0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
154e0 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
154f0 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
15500 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15510 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
15520 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
15530 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
15540 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
15550 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
15560 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
15570 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
15580 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
15590 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
155a0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
155b0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
155c0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
155d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
155e0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
155f0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
15600 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
15610 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
15620 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
15630 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
15640 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
15650 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
15660 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
15670 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
15680 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
15690 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
156a0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
156b0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
156c0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
156d0 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
156e0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
156f0 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
15700 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
15710 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
15720 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
15730 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
15740 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
15750 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
15760 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
15770 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
15780 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
15790 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
157a0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
157b0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
157c0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
157d0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
157e0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
157f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15800 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
15810 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
15820 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
15830 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
15840 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
15850 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
15860 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
15870 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
15880 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15890 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
158a0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
158b0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
158c0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
158d0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
158e0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
158f0 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
15900 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
15910 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
15920 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
15930 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
15940 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
15950 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
15960 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
15970 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
15980 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
15990 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
159a0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
159b0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
159c0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
159d0 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
159e0 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
159f0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
15a00 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
15a10 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
15a20 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
15a30 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
15a40 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
15a50 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
15a60 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
15a70 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
15a80 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
15a90 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
15aa0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
15ab0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
15ac0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
15ad0 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
15ae0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
15af0 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
15b00 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
15b10 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
15b20 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
15b30 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
15b40 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
15b50 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
15b60 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
15b70 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
15b80 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
15b90 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
15ba0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
15bb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15bc0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
15bd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15be0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
15bf0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
15c00 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
15c10 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
15c20 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
15c30 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15c40 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
15c50 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
15c60 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
15c70 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
15c80 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
15c90 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
15ca0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
15cb0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
15cc0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
15cd0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15ce0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
15cf0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
15d00 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
15d10 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
15d20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
15d30 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
15d40 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
15d50 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
15d60 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
15d70 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
15d80 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
15d90 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
15da0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
15db0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
15dc0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
15dd0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
15de0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
15df0 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
15e00 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
15e10 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
15e20 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
15e30 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
15e40 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
15e50 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
15e60 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
15e70 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
15e80 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
15e90 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
15ea0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
15eb0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
15ec0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
15ed0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
15ee0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
15ef0 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
15f00 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
15f10 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
15f20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
15f30 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
15f40 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
15f50 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
15f60 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
15f70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15f80 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
15f90 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  loc()..**.** ^(T
15fa0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
15fb0 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
15fc0 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
15fd0 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
15fe0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
15ff0 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
16000 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
16010 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
16020 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
16030 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16040 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
16050 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
16060 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49  parameter.)^ ^ I
16070 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
16080 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16090 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
160a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
160b0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
160c0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
160d0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
160e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
160f0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
16100 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16110 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16120 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  c()..** ^If the 
16130 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16140 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
16150 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
16160 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
16170 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
16180 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
16190 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
161a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29   sqlite3_free(P)
161b0 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20   where P is the 
161c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
161d0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
161e0 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  oc()..** ^sqlite
161f0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
16200 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
16210 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
16220 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
16230 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
16240 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73  ize or NULL if s
16250 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
16260 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
16270 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
16280 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
16290 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
162a0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
162b0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
162c0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
162d0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
162e0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
162f0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
16300 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
16310 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70  lloc() and the p
16320 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
16330 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  is freed..** ^If
16340 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16350 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
16360 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
16370 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
16380 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
16390 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
163a0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
163b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
163c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
163d0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
163e0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
163f0 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
16400 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  dary..**.** In S
16410 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
16420 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
16430 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
16440 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
16450 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
16460 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
16470 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
16480 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
16490 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
164a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
164b0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
164c0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
164d0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
164e0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
164f0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
16500 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
16510 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
16520 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
16530 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
16540 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
16550 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
16560 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
16570 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
16580 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
16590 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
165a0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
165b0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
165c0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
165d0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
165e0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
165f0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
16600 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
16610 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
16620 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
16630 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
16640 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
16650 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
16660 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
16670 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
16680 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
16690 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
166a0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
166b0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
166c0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
166d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
166e0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
166f0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
16700 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
16710 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
16720 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
16730 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16740 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
16750 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
16760 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
16770 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
16780 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
16790 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
167a0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
167b0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
167c0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
167d0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
167e0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
167f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
16800 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
16810 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
16820 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
16830 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
16840 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
16850 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
16860 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
16870 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16880 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
16890 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
168a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
168b0 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
168c0 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
168d0 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
168e0 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
168f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16900 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
16910 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
16920 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
16930 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
16940 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
16950 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
16960 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
16970 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
16980 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
16990 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
169a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
169b0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
169c0 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
169d0 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
169e0 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
169f0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
16a00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16a10 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
16a20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
16a30 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
16a40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16a50 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
16a60 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
16a70 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
16a80 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
16a90 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
16aa0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16ab0 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
16ac0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
16ad0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
16ae0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
16af0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
16b00 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
16b10 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
16b20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
16b30 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
16b40 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
16b50 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
16b60 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
16b70 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
16b80 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16b90 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
16ba0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
16bb0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
16bc0 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
16bd0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
16be0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
16bf0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
16c00 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
16c10 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
16c20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
16c30 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
16c40 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
16c50 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
16c60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16c70 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
16c80 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
16c90 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
16ca0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
16cb0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
16cc0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
16cd0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
16ce0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
16cf0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
16d00 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
16d10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
16d20 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
16d30 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
16d40 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
16d50 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
16d60 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
16d70 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
16d80 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
16d90 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
16da0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
16db0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
16dc0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
16dd0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
16de0 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
16df0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
16e00 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
16e10 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
16e20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
16e30 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
16e40 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
16e50 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
16e60 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
16e70 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
16e80 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
16e90 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
16ea0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
16eb0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
16ec0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
16ed0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
16ee0 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
16ef0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
16f00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
16f10 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
16f20 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
16f30 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
16f40 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
16f50 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
16f60 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
16f70 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
16f80 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
16f90 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
16fa0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
16fb0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
16fc0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
16fd0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
16fe0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
16ff0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
17000 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
17010 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
17020 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
17030 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
17040 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
17050 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
17060 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
17070 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
17080 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
17090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
170a0 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
170b0 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
170c0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
170d0 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
170e0 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  a authorizer cal
170f0 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
17100 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
17110 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17120 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
17130 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17140 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
17150 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17160 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
17170 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
17180 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
17190 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
171a0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
171b0 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
171c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
171d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
171e0 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
171f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
17200 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
17210 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
17220 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
17230 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
17240 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
17250 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
17260 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
17270 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
17280 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
17290 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
172a0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
172b0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
172c0 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
172d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
172e0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
172f0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
17300 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
17310 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
17320 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
17330 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
17340 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
17350 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
17360 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
17370 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
17380 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
17390 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
173a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
173b0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
173c0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
173d0 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
173e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
173f0 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
17400 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
17410 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
17420 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
17430 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
17440 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
17450 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
17460 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
17470 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
17480 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
17490 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
174a0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
174b0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
174c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
174d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
174e0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
174f0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
17500 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
17510 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
17520 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
17530 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
17540 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17550 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
17560 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
17570 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
17580 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
17590 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
175a0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
175b0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
175c0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
175d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
175e0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
175f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17600 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
17610 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
17620 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17630 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
17640 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
17650 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
17660 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
17670 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
17680 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
17690 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
176a0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
176b0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
176c0 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
176d0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
176e0 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
176f0 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
17700 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
17710 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
17720 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
17730 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
17740 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
17750 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
17760 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
17770 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
17780 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
17790 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
177a0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
177b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
177c0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
177d0 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
177e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
177f0 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
17800 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
17810 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
17820 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
17830 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
17840 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
17850 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
17860 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
17870 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
17880 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
17890 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
178a0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
178b0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
178c0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
178d0 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
178e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
178f0 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
17900 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
17910 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
17920 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
17930 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
17940 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
17950 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
17960 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
17970 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
17980 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
17990 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
179a0 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
179b0 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
179c0 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
179d0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
179e0 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
179f0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
17a00 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
17a10 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
17a20 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
17a30 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
17a40 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
17a50 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
17a60 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
17a70 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
17a80 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
17a90 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
17aa0 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
17ab0 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
17ac0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
17ad0 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
17ae0 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
17af0 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
17b00 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
17b10 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
17b20 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
17b30 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
17b40 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
17b50 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
17b60 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
17b70 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
17b80 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
17b90 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
17ba0 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
17bb0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
17bc0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
17bd0 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
17be0 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
17bf0 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
17c00 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
17c10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
17c20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
17c30 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
17c40 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
17c50 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
17c60 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
17c70 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
17c80 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
17c90 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
17ca0 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
17cb0 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
17cc0 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
17cd0 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
17ce0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
17cf0 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
17d00 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
17d10 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
17d20 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
17d30 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
17d40 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
17d50 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
17d60 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
17d70 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
17d80 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
17d90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17da0 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
17db0 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
17dc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17dd0 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
17de0 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
17df0 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
17e00 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
17e10 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
17e20 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
17e30 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
17e40 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
17e50 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
17e60 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
17e70 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
17e80 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
17e90 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
17ea0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
17eb0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
17ec0 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
17ed0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
17ee0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
17ef0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
17f00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
17f10 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
17f20 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
17f30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17f40 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
17f50 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
17f60 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
17f70 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
17f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17f90 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
17fa0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
17fb0 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
17fc0 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
17fd0 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
17fe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17ff0 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
18000 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
18010 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
18020 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
18030 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
18040 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
18050 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
18060 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
18070 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
18080 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
18090 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
180a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
180b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
180c0 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
180d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
180e0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
180f0 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
18100 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
18110 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
18120 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
18130 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
18140 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
18150 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
18160 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
18170 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
18180 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
18190 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
181a0 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
181b0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
181c0 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
181d0 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ge..*/.int sqlit
181e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
181f0 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  r(.  sqlite3*,. 
18200 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f   int (*xAuth)(vo
18210 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
18220 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
18230 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
18240 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64  t char*),.  void
18250 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a   *pUserData.);..
18260 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18270 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72  Authorizer Retur
18280 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
18290 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
182a0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
182b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
182c0 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
182d0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
182e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
182f0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
18300 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
18310 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
18320 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
18330 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
18340 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
18350 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
18360 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18370 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
18380 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
18390 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
183a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
183b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
183c0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
183d0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
183e0 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
183f0 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
18400 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
18410 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
18420 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
18430 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
18440 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
18450 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
18460 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
18470 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
18480 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18490 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
184a0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
184b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
184c0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
184d0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
184e0 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
184f0 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
18500 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
18510 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
18520 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
18530 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
18540 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
18550 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
18560 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
18570 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
18580 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
18590 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
185a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
185b0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
185c0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
185d0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
185e0 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
185f0 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
18600 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
18610 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
18620 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
18630 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
18640 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
18650 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
18660 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
18670 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
18680 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
18690 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
186a0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
186b0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
186c0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
186d0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
186e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
186f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
18700 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
18710 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
18720 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
18730 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
18740 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
18750 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18760 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
18770 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
18780 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
18790 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
187a0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
187b0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
187c0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
187d0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
187e0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
187f0 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
18800 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
18810 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18820 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18830 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
18840 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
18850 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
18860 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18870 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
18880 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
18890 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
188a0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
188b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
188c0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
188d0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
188e0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
188f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18900 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18910 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
18920 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
18930 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
18940 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18950 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18960 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
18970 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18980 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18990 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
189a0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
189b0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
189c0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
189d0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
189e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
189f0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
18a00 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
18a10 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
18a20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18a30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18a40 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
18a50 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
18a60 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
18a70 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18a80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18a90 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
18aa0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
18ab0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
18ac0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18ad0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ae0 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
18af0 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
18b00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18b10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18b20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18b30 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
18b40 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
18b50 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
18b60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
18b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18b80 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
18b90 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
18ba0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18bb0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18bc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18bd0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
18be0 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
18bf0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
18c00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18c10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18c20 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
18c30 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
18c40 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
18c50 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18c60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18c70 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
18c80 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
18c90 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
18ca0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18cc0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
18cd0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
18ce0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
18cf0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18d10 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
18d20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
18d30 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
18d40 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18d50 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
18d60 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
18d70 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
18d80 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
18d90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18da0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
18db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
18dc0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
18dd0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
18de0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18df0 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
18e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
18e10 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
18e20 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
18e30 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
18e40 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
18e50 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
18e60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18e70 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
18e80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18e90 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
18ea0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
18eb0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
18ec0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18ed0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18ee0 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
18ef0 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
18f00 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
18f10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18f20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18f30 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
18f40 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
18f50 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18f60 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
18f70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18f80 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
18f90 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
18fa0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
18fb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18fd0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
18fe0 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
18ff0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
19000 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19020 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
19030 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
19040 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
19050 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
19060 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19070 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
19080 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
19090 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
190a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
190b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
190c0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
190d0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
190e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
190f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19110 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
19120 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
19130 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
19140 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
19150 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19160 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
19170 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
19180 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
19190 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
191a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
191b0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
191c0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
191d0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
191e0 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
191f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
19200 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
19210 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
19220 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
19230 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
19240 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
19250 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19260 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
19270 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
19280 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
19290 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
192a0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
192b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
192c0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
192d0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
192e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
192f0 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
19300 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
19310 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
19320 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
19330 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
19340 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
19350 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
19360 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
19370 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
19380 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
19390 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
193a0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
193b0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
193c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
193d0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
193e0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
193f0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
19400 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
19410 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
19420 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
19430 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
19440 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
19450 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
19460 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
19470 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
19480 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
19490 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
194a0 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
194b0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
194c0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
194d0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
194e0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
194f0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
19500 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ^.**.** ^The cal
19510 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
19520 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
19530 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
19540 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
19550 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
19560 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
19570 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19580 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
19590 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
195a0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
195b0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
195c0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
195d0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
195e0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
195f0 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f 69  k to run..*/.voi
19600 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
19610 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
19620 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
19630 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
19640 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
19650 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
19660 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
19670 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
19680 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
19690 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
196a0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
196b0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
196c0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
196d0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
196e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
196f0 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20  tine configures 
19700 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
19710 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f  ion - the.** pro
19720 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
19730 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
19740 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
19750 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e  ring long.** run
19760 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
19770 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
19780 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19790 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
197a0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
197b0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
197c0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
197d0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
197e0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
197f0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
19800 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ry..**.** ^If th
19810 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19820 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19830 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
19840 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
19850 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
19860 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
19870 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
19880 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
19890 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
198a0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
198b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
198c0 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  ess handler must
198d0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
198e0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
198f0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
19900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
19910 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
19920 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
19930 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
19940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19950 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
19960 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
19970 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
19980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19990 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
199a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
199b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
199c0 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
199d0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
199e0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
199f0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
19a00 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
19a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
19a20 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
19a30 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
19a40 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
19a50 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
19a60 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
19a70 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20  e whose name is 
19a80 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20  given by the.** 
19a90 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
19aa0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
19ab0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
19ac0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
19ad0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
19ae0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
19af0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
19b00 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
19b10 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
19b20 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
19b30 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
19b40 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
19b50 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
19b60 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
19b70 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
19b80 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
19b90 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
19ba0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
19bb0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
19bc0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
19bd0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
19be0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
19bf0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
19c00 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
19c10 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
19c20 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
19c30 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
19c40 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
19c50 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
19c60 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
19c70 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
19c80 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
19c90 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
19ca0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
19cb0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
19cc0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
19cd0 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
19ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
19cf0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
19d00 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
19d10 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
19d20 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
19d30 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
19d40 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
19d50 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
19d60 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
19d70 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
19d80 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
19d90 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
19da0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
19db0 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
19dc0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
19dd0 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
19de0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
19df0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
19e00 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
19e10 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
19e20 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
19e30 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
19e40 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
19e50 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
19e60 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
19e70 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
19e80 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
19e90 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
19ea0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
19eb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
19ec0 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
19ed0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
19ee0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
19ef0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
19f00 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
19f10 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
19f20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
19f30 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
19f40 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
19f50 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
19f60 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
19f70 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
19f80 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
19f90 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
19fa0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
19fb0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
19fc0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
19fd0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
19fe0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
19ff0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
1a000 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1a010 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1a020 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1a030 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1a040 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1a050 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1a060 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
1a070 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
1a080 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1a090 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  CHE],.** and/or 
1a0a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
1a0b0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73  VATECACHE] flags
1a0c0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
1a0d0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
1a0e0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
1a0f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1a100 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a110 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
1a120 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
1a130 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1a140 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
1a150 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
1a160 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
1a170 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1a180 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1a190 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1a1a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1a1b0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1a1c0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1a1d0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1a1e0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1a1f0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1a200 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1a210 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1a220 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1a230 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1a240 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1a250 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1a260 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1a270 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1a280 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1a290 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1a2a0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
1a2b0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
1a2c0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1a2d0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1a2e0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1a2f0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
1a300 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69  eates it if.** i
1a310 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1a320 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1a330 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1a340 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1a350 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1a360 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1a370 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1a380 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1a390 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1a3a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1a3b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1a3c0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1a3d0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1a3e0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
1a3f0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
1a400 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1a410 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
1a420 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
1a430 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1a440 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1a450 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c  LMUTEX],.** [SQL
1a460 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1a470 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51  ACHE] and/or [SQ
1a480 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1a490 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
1a4a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1a4b0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1a4c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1a4d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1a4e0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1a4f0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1a500 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1a510 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1a520 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1a530 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1a540 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1a550 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1a560 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1a570 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1a580 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1a590 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1a5a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1a5b0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1a5c0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1a5d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1a5e0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1a5f0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1a600 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1a610 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1a620 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1a630 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1a640 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1a650 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1a660 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1a670 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1a680 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1a690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a6a0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1a6b0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1a6c0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1a6d0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1a6e0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1a6f0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1a700 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1a710 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1a720 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1a730 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1a740 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1a750 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1a760 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a770 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1a780 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1a790 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1a7a0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1a7b0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1a7c0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1a7d0 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1a7e0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1a7f0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1a800 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1a810 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1a820 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1a830 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1a840 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1a850 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1a860 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a870 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1a880 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1a890 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1a8a0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1a8b0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1a8c0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1a8d0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1a8e0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1a8f0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1a900 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1a910 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1a920 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1a930 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1a940 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1a950 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1a960 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1a970 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1a980 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1a990 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1a9a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1a9b0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1a9c0 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1a9d0 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1a9e0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1a9f0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1aa00 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1aa10 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1aa20 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1aa30 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1aa40 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1aa50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1aa60 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1aa70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1aa80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1aa90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1aaa0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1aab0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1aac0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1aad0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1aae0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1aaf0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1ab00 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1ab10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1ab20 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1ab30 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1ab40 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1ab50 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1ab60 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1ab70 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1ab80 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1ab90 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1aba0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1abb0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1abc0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1abd0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1abe0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1abf0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1ac00 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1ac10 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1ac20 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1ac30 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1ac40 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1ac50 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1ac60 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1ac70 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1ac80 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1ac90 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1aca0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1acb0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1acc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1acd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1ace0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
1acf0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1ad00 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1ad10 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1ad20 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1ad30 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1ad40 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1ad50 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1ad60 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
1ad70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
1ad80 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1ad90 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1ada0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
1adb0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1adc0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1add0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1ade0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1adf0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1ae00 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1ae10 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1ae20 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1ae30 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1ae40 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1ae50 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1ae60 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1ae70 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1ae80 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1ae90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1aea0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1aeb0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1aec0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1aed0 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
1aee0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
1aef0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
1af00 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1af10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1af20 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1af30 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1af40 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1af50 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1af60 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1af70 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1af80 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1af90 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1afa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1afb0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1afc0 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1afd0 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1afe0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1aff0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1b000 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1b010 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1b020 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1b030 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1b040 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1b050 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1b060 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
1b070 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
1b080 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
1b090 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1b0a0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
1b0b0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
1b0c0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
1b0d0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1b0e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1b0f0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1b100 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1b110 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1b120 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1b130 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1b140 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1b150 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1b160 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1b170 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
1b180 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1b190 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1b1a0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1b1b0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1b1c0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1b1d0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1b1e0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1b1f0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1b200 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1b210 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1b220 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1b230 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1b240 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1b250 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1b260 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1b270 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
1b280 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1b290 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1b2a0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
1b2b0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
1b2c0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
1b2d0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
1b2e0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
1b2f0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
1b300 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
1b310 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
1b320 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
1b330 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1b340 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1b350 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1b360 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1b370 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1b380 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1b390 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1b3a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1b3b0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1b3c0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1b3d0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1b3e0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1b3f0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1b400 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1b410 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1b420 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1b430 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1b440 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1b450 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1b460 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1b470 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1b480 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1b490 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1b4a0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1b4b0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1b4c0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1b4d0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1b4e0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1b4f0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1b500 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1b510 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1b520 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1b530 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1b540 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1b550 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1b560 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1b570 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1b580 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1b590 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1b5a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1b5b0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1b5c0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
1b5d0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1b5e0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1b5f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1b600 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1b610 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1b620 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1b630 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1b640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1b650 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1b660 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1b670 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1b680 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1b690 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1b6a0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1b6b0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1b6c0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1b6d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1b6e0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1b6f0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1b700 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1b710 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1b720 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1b730 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1b740 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1b750 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1b760 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1b770 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1b780 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1b790 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1b7a0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1b7b0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1b7c0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1b7d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1b7e0 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1b7f0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1b800 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1b810 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1b820 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1b830 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1b840 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1b850 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1b860 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1b870 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b880 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1b890 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1b8a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1b8b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1b8c0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1b8d0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1b8e0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1b8f0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1b900 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1b910 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1b920 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1b930 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1b940 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1b950 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1b960 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1b970 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1b980 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1b990 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1b9a0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1b9b0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1b9c0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1b9d0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1b9e0 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
1b9f0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
1ba00 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1ba10 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1ba20 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1ba30 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1ba40 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1ba50 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1ba60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1ba70 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1ba80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ba90 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1baa0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1bab0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1bac0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1bad0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1bae0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1baf0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1bb00 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1bb10 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1bb20 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1bb30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1bb40 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1bb50 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1bb60 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63  truct.  The func
1bb70 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1bb80 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a   old limit.)^.**
1bb90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
1bba0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1bbb0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1bbc0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1bbd0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65  ed..** ^(For the
1bbe0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
1bbf0 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  of SQLITE_LIMIT_
1bc00 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a  XYZ there is a .
1bc10 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
1bc20 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
1bc30 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  * set by a compi
1bc40 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f  le-time C prepro
1bc50 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d  cessor macro nam
1bc60 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  ed .** [limits |
1bc70 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d   SQLITE_MAX_XYZ]
1bc80 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
1bc90 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
1bca0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
1bcb0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
1bcc0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
1bcd0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
1bce0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
1bcf0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
1bd00 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
1bd10 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
1bd20 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52  r bound..**.** R
1bd30 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
1bd40 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1bd50 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1bd60 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1bd70 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1bd80 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1bd90 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1bda0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1bdb0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1bdc0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1bdd0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1bde0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1bdf0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1be00 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
1be10 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1be20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1be30 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1be40 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1be50 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1be60 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
1be70 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
1be80 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
1be90 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
1bea0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
1beb0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
1bec0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
1bed0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
1bee0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
1bef0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
1bf00 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
1bf10 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
1bf20 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
1bf30 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
1bf40 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
1bf50 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
1bf60 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
1bf70 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
1bf80 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
1bf90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1bfa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
1bfb0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
1bfc0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
1bfd0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
1bfe0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
1bff0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
1c000 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
1c010 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
1c020 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
1c030 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1c040 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
1c050 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
1c060 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
1c070 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
1c080 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
1c090 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
1c0a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
1c0b0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
1c0c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1c0d0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
1c0e0 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
1c0f0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1c100 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
1c110 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1c120 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1c130 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1c140 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
1c150 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
1c160 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
1c170 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
1c180 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1c190 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
1c1a0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
1c1b0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1c1c0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
1c1d0 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
1c1e0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
1c1f0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
1c200 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
1c210 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
1c220 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1c230 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1c240 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1c250 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1c260 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1c270 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1c280 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  row.<dd>)^.**.**
1c290 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c2a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1c2b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c2c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1c2d0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1c2e0 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
1c2f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c300 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1c310 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
1c320 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1c330 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1c340 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
1c350 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
1c360 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
1c370 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
1c380 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c390 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
1c3a0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
1c3b0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
1c3c0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
1c3d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1c3e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1c3f0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
1c400 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c410 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
1c420 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
1c430 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
1c440 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1c450 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1c460 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
1c470 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c480 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c490 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1c4a0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1c4b0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
1c4c0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1c4d0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1c4e0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c4f0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c500 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1c510 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1c520 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1c530 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1c540 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1c550 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1c560 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c570 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
1c580 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1c590 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1c5a0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
1c5b0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
1c5c0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1c5d0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1c5e0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
1c5f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c600 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
1c610 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
1c620 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
1c630 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c640 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1c650 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1c660 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1c670 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
1c680 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
1c690 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
1c6a0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
1c6b0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
1c6c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c6d0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1c6e0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
1c6f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1c700 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20  er of variables 
1c710 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1c720 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20  ent that can.** 
1c730 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29 5e  be bound.</dd>)^
1c740 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c750 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1c760 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1c770 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c780 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
1c790 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
1c7a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1c7b0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1c7c0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1c7d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c7e0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1c7f0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1c800 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1c810 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1c820 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1c830 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1c840 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1c850 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1c860 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1c870 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1c880 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1c890 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1c8a0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1c8b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1c8c0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1c8d0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1c8e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1c8f0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1c900 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1c910 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c920 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1c930 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1c940 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c950 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1c960 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1c970 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c980 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1c990 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
1c9a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c9b0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1c9c0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
1c9d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c9e0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1c9f0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
1ca00 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1ca10 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1ca20 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1ca30 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1ca40 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1ca50 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1ca60 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1ca70 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1ca80 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1ca90 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1caa0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1cab0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1cac0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1cad0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1cae0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
1caf0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1cb00 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1cb10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1cb20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
1cb30 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
1cb40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cb50 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
1cb60 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
1cb70 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1cb80 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
1cb90 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1cba0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1cbb0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1cbc0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1cbd0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1cbe0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1cbf0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1cc00 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1cc10 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
1cc20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1cc30 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1cc40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1cc50 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1cc60 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
1cc70 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1cc80 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1cc90 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1cca0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1ccb0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1ccc0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
1ccd0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1cce0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
1ccf0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
1cd00 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
1cd10 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
1cd20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
1cd30 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1cd40 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
1cd50 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
1cd60 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
1cd70 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
1cd80 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
1cd90 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
1cda0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
1cdb0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
1cdc0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
1cdd0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
1cde0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
1cdf0 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
1ce00 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
1ce10 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
1ce20 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
1ce30 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
1ce40 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
1ce50 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
1ce60 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
1ce70 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1ce80 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
1ce90 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
1cea0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
1ceb0 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a  nator bytes..**.
1cec0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
1ced0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
1cee0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1cef0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
1cf00 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
1cf10 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1cf20 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1cf30 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
1cf40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
1cf50 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
1cf60 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
1cf70 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
1cf80 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
1cf90 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
1cfa0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
1cfb0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
1cfc0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1cfd0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1cfe0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1cff0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1d000 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1d010 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d020 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
1d030 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
1d040 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
1d050 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
1d060 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
1d070 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
1d080 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
1d090 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
1d0a0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
1d0b0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
1d0c0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
1d0d0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
1d0e0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
1d0f0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
1d100 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
1d110 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d120 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1d130 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
1d140 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
1d150 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
1d160 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
1d170 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
1d180 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
1d190 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1d1a0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
1d1b0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1d1c0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
1d1d0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1d1e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1d1f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1d200 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1d210 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1d220 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1d230 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1d240 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1d250 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1d260 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1d270 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1d280 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1d290 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1d2a0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1d2b0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1d2c0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
1d2d0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1d2e0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1d2f0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1d300 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1d310 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1d320 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1d330 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1d340 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1d350 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1d360 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1d370 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1d380 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
1d390 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
1d3a0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1d3b0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1d3c0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1d3d0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1d3e0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1d3f0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1d400 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1d410 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1d420 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1d430 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1d440 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1d450 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1d460 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1d470 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20 74  it again.  ^If t
1d480 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
1d490 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61  anged in.** a wa
1d4a0 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  y that makes the
1d4b0 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
1d4c0 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
1d4d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1d4e0 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
1d4f0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1d500 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
1d510 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1d520 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  or, [SQLITE_SCHE
1d530 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20  MA] is.** now a 
1d540 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
1d550 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
1d560 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
1d570 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
1d580 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
1d590 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
1d5a0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1d5b0 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
1d5c0 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20   text.** of the 
1d5d0 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68  parsing error th
1d5e0 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
1d5f0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1d600 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69   return..** </li
1d610 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1d620 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
1d630 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
1d640 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
1d650 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
1d660 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
1d670 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
1d680 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
1d690 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
1d6a0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
1d6b0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
1d6c0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
1d6d0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
1d6e0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
1d6f0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
1d700 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
1d710 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
1d720 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
1d730 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1d740 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
1d750 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
1d760 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
1d770 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
1d780 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
1d790 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
1d7a0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
1d7b0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
1d7c0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
1d7d0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1d7e0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
1d7f0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
1d800 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20   the value of a 
1d810 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
1d820 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
1d830 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65  the WHERE clause
1d840 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67 65   might.** change
1d850 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 20   the query plan 
1d860 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
1d870 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
1d880 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61 75  ent may be.** au
1d890 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
1d8a0 6d 70 69 6c 65 64 20 28 61 73 20 69 66 20 74 68  mpiled (as if th
1d8b0 65 72 65 20 68 61 64 20 62 65 65 6e 20 61 20 73  ere had been a s
1d8c0 63 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f 6e  chema change) on
1d8d0 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20 5b   the first .** [
1d8e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d8f0 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
1d900 6e 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68 65  ny change to the
1d910 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69   .** [sqlite3_bi
1d920 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
1d930 67 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72 61  gs] of the [para
1d940 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69  meter]. .** </li
1d950 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
1d960 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1d970 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1d980 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1d990 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1d9a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1d9b0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1d9c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1d9d0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1d9e0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1d9f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1da00 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1da10 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1da20 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1da30 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1da40 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1da50 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1da60 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1da70 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1da80 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1da90 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1daa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1dab0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
1dac0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1dad0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1dae0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1daf0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1db00 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1db10 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1db20 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1db30 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1db40 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1db50 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1db60 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1db70 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1db80 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1db90 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1dba0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1dbb0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1dbc0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1dbd0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1dbe0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1dbf0 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
1dc00 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1dc10 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1dc20 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1dc30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1dc40 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1dc50 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1dc60 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1dc70 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1dc80 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1dc90 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1dca0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1dcb0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1dcc0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1dcd0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1dce0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1dcf0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1dd00 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1dd10 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1dd20 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1dd30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1dd40 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
1dd50 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1dd60 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1dd70 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1dd80 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1dd90 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1dda0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1ddb0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1ddc0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1ddd0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1dde0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1ddf0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1de00 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1de10 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1de20 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1de30 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1de40 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1de50 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1de60 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1de70 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1de80 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
1de90 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
1dea0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
1deb0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1dec0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
1ded0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
1dee0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
1def0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
1df00 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
1df10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
1df20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
1df30 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
1df40 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1df50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1df60 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1df70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1df80 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
1df90 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
1dfa0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1dfb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dfc0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
1dfd0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
1dfe0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1dff0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e000 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
1e010 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1e020 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
1e030 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
1e040 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
1e050 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
1e060 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
1e070 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
1e080 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1e090 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
1e0a0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
1e0b0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
1e0c0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
1e0d0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
1e0e0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e0f0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
1e100 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
1e110 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
1e120 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
1e130 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
1e140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e150 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
1e160 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
1e170 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
1e180 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
1e190 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
1e1a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e1b0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
1e1c0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
1e1d0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
1e1e0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
1e1f0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
1e200 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
1e210 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
1e220 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
1e230 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
1e240 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
1e250 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e260 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
1e270 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e280 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
1e290 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
1e2a0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
1e2b0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
1e2c0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
1e2d0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
1e2e0 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74    A internal mut
1e2f0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1e300 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
1e310 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e320 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
1e330 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
1e340 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1e350 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e360 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
1e370 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
1e380 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
1e390 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
1e3a0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
1e3b0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
1e3c0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
1e3d0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
1e3e0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
1e3f0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
1e400 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
1e410 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
1e420 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
1e430 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
1e440 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
1e450 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
1e460 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
1e470 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1e480 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1e490 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1e4a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
1e4b0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
1e4c0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
1e4d0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
1e4e0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
1e4f0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
1e500 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1e510 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
1e520 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
1e530 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
1e540 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70  etween between p
1e550 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1e560 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1e570 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e580 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
1e590 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
1e5a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1e5b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e5c0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
1e5d0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
1e5e0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
1e5f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1e600 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1e610 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1e620 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
1e630 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
1e640 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1e650 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
1e660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
1e670 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
1e680 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
1e690 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1e6a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
1e6b0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
1e6c0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
1e6d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
1e6e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1e6f0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
1e700 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
1e710 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
1e720 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
1e730 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
1e740 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
1e750 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e760 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
1e770 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1e780 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
1e790 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
1e7a0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
1e7b0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
1e7c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
1e7d0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
1e7e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
1e7f0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
1e800 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
1e810 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
1e820 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
1e830 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
1e840 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
1e850 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
1e860 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
1e870 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1e880 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
1e890 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1e8a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1e8b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
1e8c0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
1e8d0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
1e8e0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
1e8f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
1e900 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
1e910 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
1e920 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
1e930 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
1e940 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
1e950 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
1e960 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
1e970 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
1e980 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
1e990 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
1e9a0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
1e9b0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
1e9c0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
1e9d0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
1e9e0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
1e9f0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
1ea00 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
1ea10 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
1ea20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
1ea30 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
1ea40 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
1ea50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1ea60 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
1ea70 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
1ea80 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
1ea90 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
1eaa0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
1eab0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
1eac0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
1ead0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1eae0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
1eaf0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
1eb00 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
1eb10 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
1eb20 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
1eb30 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
1eb40 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
1eb50 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
1eb60 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
1eb70 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
1eb80 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
1eb90 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
1eba0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
1ebb0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
1ebc0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
1ebd0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
1ebe0 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
1ebf0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
1ec00 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
1ec10 63 20 69 64 65 6e 74 69 66 65 72 2e 29 5e 20 20  c identifer.)^  
1ec20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
1ec30 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
1ec40 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
1ec50 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
1ec60 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
1ec70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
1ec80 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
1ec90 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1eca0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
1ecb0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
1ecc0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1ecd0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
1ece0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1ecf0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
1ed00 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1ed10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1ed20 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
1ed30 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
1ed40 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ed50 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1ed60 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
1ed70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
1ed80 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1ed90 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
1eda0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
1edb0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
1edc0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1edd0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
1ede0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
1edf0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
1ee00 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
1ee10 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
1ee20 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
1ee30 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
1ee40 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
1ee50 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
1ee60 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
1ee70 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
1ee80 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
1ee90 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
1eea0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
1eeb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1eec0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1eed0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
1eee0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
1eef0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
1ef00 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
1ef10 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
1ef20 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
1ef30 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
1ef40 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
1ef50 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
1ef60 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
1ef70 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1ef80 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
1ef90 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
1efa0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
1efb0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1efc0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1efd0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1efe0 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
1eff0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
1f000 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
1f010 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
1f020 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1f030 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
1f040 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
1f050 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
1f060 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1f070 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
1f080 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
1f090 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
1f0a0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
1f0b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
1f0c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
1f0d0 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
1f0e0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
1f0f0 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
1f100 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
1f110 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
1f120 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
1f130 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
1f140 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1f150 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
1f160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f170 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
1f180 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
1f190 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
1f1a0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
1f1b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
1f1c0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
1f1d0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
1f1e0 68 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66  hed with it. ^If
1f1f0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1f200 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
1f210 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
1f220 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
1f230 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
1f240 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
1f250 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
1f260 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
1f270 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
1f280 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
1f290 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
1f2a0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1f2b0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
1f2c0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1f2d0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
1f2e0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
1f2f0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
1f300 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
1f310 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
1f320 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1f330 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
1f340 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
1f350 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1f360 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1f370 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1f380 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1f390 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1f3a0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
1f3b0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
1f3c0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
1f3d0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
1f3e0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
1f3f0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
1f400 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
1f410 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
1f420 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
1f430 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
1f440 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
1f450 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
1f460 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
1f470 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
1f480 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
1f490 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
1f4a0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
1f4b0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
1f4c0 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
1f4d0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
1f4e0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
1f4f0 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
1f500 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
1f510 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1f520 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1f530 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1f540 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
1f550 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f560 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
1f570 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1f580 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
1f590 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f5a0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
1f5b0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
1f5c0 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
1f5d0 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
1f5e0 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
1f5f0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
1f600 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
1f610 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
1f620 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
1f630 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
1f640 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
1f650 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
1f660 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
1f670 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1f680 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
1f690 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
1f6a0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
1f6b0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
1f6c0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
1f6d0 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
1f6e0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1f6f0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
1f700 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
1f710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
1f720 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1f730 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
1f740 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
1f750 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
1f760 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
1f770 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
1f780 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
1f790 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
1f7a0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
1f7b0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
1f7c0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
1f7d0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
1f7e0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
1f7f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1f800 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f810 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
1f820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1f830 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1f840 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1f850 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f860 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
1f870 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1f880 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
1f890 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1f8a0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
1f8b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1f8c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
1f8d0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
1f8e0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
1f8f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f900 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
1f910 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
1f920 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f930 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
1f940 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
1f950 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
1f960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
1f970 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1f980 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
1f990 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
1f9a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f9b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
1f9c0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
1f9d0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1f9e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
1f9f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1fa00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
1fa10 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
1fa20 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
1fa30 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
1fa40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1fa50 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
1fa60 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
1fa70 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
1fa80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1fa90 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
1faa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
1fab0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
1fac0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
1fad0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
1fae0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
1faf0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
1fb00 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
1fb10 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
1fb20 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
1fb30 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
1fb40 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
1fb50 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
1fb60 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
1fb70 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
1fb80 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
1fb90 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
1fba0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
1fbb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1fbc0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
1fbd0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
1fbe0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
1fbf0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
1fc00 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
1fc10 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
1fc20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
1fc30 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
1fc40 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
1fc50 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
1fc60 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
1fc70 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
1fc80 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
1fc90 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
1fca0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
1fcb0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
1fcc0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
1fcd0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
1fce0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
1fcf0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1fd00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1fd10 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1fd20 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1fd30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1fd40 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
1fd50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1fd60 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1fd70 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1fd80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1fd90 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
1fda0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fdb0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
1fdc0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
1fdd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1fde0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1fdf0 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
1fe00 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
1fe10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
1fe20 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
1fe30 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
1fe40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
1fe50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
1fe60 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1fe70 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
1fe80 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
1fe90 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
1fea0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
1feb0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
1fec0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
1fed0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
1fee0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
1fef0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
1ff00 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
1ff10 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
1ff20 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
1ff30 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
1ff40 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
1ff50 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
1ff60 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
1ff70 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
1ff80 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
1ff90 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
1ffa0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
1ffb0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
1ffc0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
1ffd0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
1ffe0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
1fff0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
20000 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
20010 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
20020 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
20030 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
20040 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
20050 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
20060 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
20070 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
20080 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
20090 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
200a0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
200b0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
200c0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
200d0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
200e0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
200f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20100 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
20110 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20120 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
20130 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
20140 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
20150 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
20160 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
20170 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
20180 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
20190 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
201a0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
201b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
201c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
201d0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
201e0 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
201f0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
20200 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
20210 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
20220 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
20230 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
20240 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
20250 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
20260 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
20270 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
20280 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
20290 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
202a0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
202b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
202c0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
202d0 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
202e0 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
202f0 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
20300 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
20310 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
20320 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
20330 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
20340 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
20350 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
20360 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
20370 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
20380 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20390 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
203a0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
203b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
203c0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
203d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
203e0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
203f0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
20400 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
20410 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
20420 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20430 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
20440 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
20450 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
20460 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20470 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
20480 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
20490 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
204a0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
204b0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
204c0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
204d0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
204e0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
204f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20500 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
20510 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
20520 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
20530 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
20540 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
20550 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
20560 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
20570 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
20580 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
20590 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
205a0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
205b0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
205c0 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
205d0 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
205e0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
205f0 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
20600 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
20610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20620 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
20630 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
20640 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
20650 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
20660 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
20670 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
20680 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
20690 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
206a0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
206b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
206c0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
206d0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
206e0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
206f0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
20700 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
20710 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
20720 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
20730 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
20740 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
20750 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
20760 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
20770 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
20780 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
20790 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
207a0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
207b0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
207c0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
207d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
207e0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
207f0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
20800 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
20810 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
20820 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
20830 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
20840 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
20850 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
20860 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
20870 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
20880 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
20890 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
208a0 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
208b0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
208c0 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
208d0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
208e0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
208f0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
20900 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
20910 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
20920 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
20930 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
20940 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
20950 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
20960 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
20970 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
20980 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
20990 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
209a0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
209b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
209c0 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
209d0 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
209e0 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
209f0 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
20a00 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
20a10 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
20a20 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
20a30 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
20a40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
20a50 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
20a60 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
20a70 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
20a80 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
20a90 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
20aa0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
20ab0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
20ac0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
20ad0 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
20ae0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20af0 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
20b00 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
20b10 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
20b20 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
20b30 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
20b40 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
20b50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
20b60 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
20b70 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
20b80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
20b90 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
20ba0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
20bb0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
20bc0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
20bd0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
20be0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
20bf0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
20c00 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
20c10 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
20c20 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
20c30 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
20c40 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
20c50 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
20c60 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
20c70 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
20c80 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
20c90 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
20ca0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
20cb0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
20cc0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
20cd0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
20ce0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
20cf0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
20d00 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
20d10 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
20d20 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
20d30 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
20d40 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
20d50 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
20d60 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
20d70 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
20d80 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
20d90 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
20da0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
20db0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
20dc0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
20dd0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
20de0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20df0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
20e00 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
20e10 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
20e20 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
20e30 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
20e40 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
20e50 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
20e60 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
20e70 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
20e80 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
20e90 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
20ea0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
20eb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
20ec0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
20ed0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
20ee0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
20ef0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
20f00 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
20f10 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
20f20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
20f30 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
20f40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
20f50 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
20f60 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
20f70 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
20f80 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
20f90 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
20fa0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
20fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20fc0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
20fd0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
20fe0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
20ff0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
21000 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
21010 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
21020 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
21030 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
21040 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
21050 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
21060 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
21070 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
21080 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
21090 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
210a0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
210b0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
210c0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
210d0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
210e0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
210f0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
21100 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
21110 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
21120 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
21130 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
21140 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
21150 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
21160 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
21170 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
21180 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
21190 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
211a0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
211b0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
211c0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
211d0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
211e0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
211f0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
21200 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
21210 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
21220 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
21230 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
21240 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
21250 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
21260 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
21270 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
21280 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
21290 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
212a0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
212b0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
212c0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
212d0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
212e0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
212f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
21300 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
21310 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
21320 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
21330 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
21340 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
21350 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21360 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
21370 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
21380 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
21390 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
213a0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
213b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
213c0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
213d0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
213e0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
213f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
21400 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
21410 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21420 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
21430 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21440 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
21450 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
21460 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
21470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
21480 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
21490 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
214a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
214b0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
214c0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
214d0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
214e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
214f0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
21500 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
21510 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
21520 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
21530 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
21540 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
21550 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
21560 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
21570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
21580 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
21590 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
215a0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
215b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
215c0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
215d0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
215e0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
215f0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
21600 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
21610 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
21620 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
21630 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
21640 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
21650 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
21660 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
21670 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
21680 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
21690 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
216a0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
216b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
216c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
216d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
216e0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
216f0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
21700 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
21710 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
21720 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
21730 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
21740 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
21750 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
21760 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
21770 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
21780 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
21790 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
217a0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
217b0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
217c0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
217d0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
217e0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
217f0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
21800 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21810 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
21820 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
21830 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
21840 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
21850 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
21860 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
21870 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
21880 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
21890 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
218a0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
218b0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
218c0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
218d0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
218e0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
218f0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
21900 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
21910 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
21920 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
21930 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
21940 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
21950 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
21960 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
21970 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
21980 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
21990 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
219a0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
219b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
219c0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
219d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
219e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
219f0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
21a00 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21a10 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
21a20 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
21a30 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
21a40 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
21a50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21a60 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
21a70 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
21a80 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
21a90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
21aa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21ab0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
21ac0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
21ad0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
21ae0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
21af0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
21b00 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
21b10 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
21b20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
21b30 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
21b40 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
21b50 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
21b60 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
21b70 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
21b80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
21b90 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
21ba0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
21bb0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
21bc0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
21bd0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
21be0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
21bf0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21c00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
21c10 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
21c20 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
21c30 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
21c40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21c50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21c60 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
21c70 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
21c80 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
21c90 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
21ca0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
21cb0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
21cc0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
21cd0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
21ce0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
21cf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
21d00 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
21d10 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
21d20 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
21d30 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
21d40 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
21d50 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
21d60 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
21d70 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
21d80 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
21d90 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
21da0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
21db0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
21dc0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
21dd0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
21de0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
21df0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
21e00 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
21e10 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
21e20 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
21e30 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
21e40 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
21e50 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
21e60 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
21e70 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
21e80 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
21e90 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
21ea0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
21eb0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
21ec0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
21ed0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
21ee0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
21ef0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
21f00 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
21f10 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
21f20 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
21f30 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
21f40 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
21f50 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
21f60 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
21f70 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
21f80 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
21f90 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
21fa0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
21fb0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
21fc0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
21fd0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
21fe0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
21ff0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
22000 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
22010 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
22020 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
22030 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
22040 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
22050 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
22060 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
22070 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
22080 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
22090 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
220a0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
220b0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
220c0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
220d0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
220e0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
220f0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
22100 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
22110 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
22120 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
22130 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
22140 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
22150 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
22160 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
22170 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
22180 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
22190 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
221a0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
221b0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
221c0 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
221d0 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
221e0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
221f0 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
22200 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
22210 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
22220 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
22230 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
22240 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
22250 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
22260 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
22270 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
22280 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
22290 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
222a0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
222b0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
222c0 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
222d0 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
222e0 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
222f0 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
22300 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
22310 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
22320 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
22330 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
22340 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
22350 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
22360 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
22370 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
22380 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
22390 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
223a0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
223b0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
223c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
223d0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
223e0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
223f0 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
22400 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
22410 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
22420 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
22430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
22440 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
22450 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
22460 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
22470 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
22480 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
22490 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
224a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
224b0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
224c0 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
224d0 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
224e0 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
224f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
22500 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
22510 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
22520 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
22530 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
22540 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
22550 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
22560 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
22570 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
22580 2c 20 69 74 20 77 61 73 20 72 65 71 75 69 72 65  , it was require
22590 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74  d.** after sqlit
225a0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
225b0 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  ed anything othe
225c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
225d0 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  OW] that.** [sql
225e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65  ite3_reset()] be
225f0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61   called before a
22600 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
22610 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
22620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
22630 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b  Failure to invok
22640 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
22650 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20  ()] in this way 
22660 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20  would.** result 
22670 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
22680 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
22690 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  m sqlite3_step()
226a0 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20  .  But after.** 
226b0 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
226c0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
226d0 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b   began calling [
226e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
226f0 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c   .** automatical
22700 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
22710 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 20 74  mstance rather t
22720 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
22730 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
22740 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
22750 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
22760 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
22770 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
22780 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
22790 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
227a0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
227b0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
227c0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
227d0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
227e0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
227f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
22800 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
22810 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
22820 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
22830 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
22840 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
22850 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
22860 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
22870 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
22880 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
22890 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
228a0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
228b0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
228c0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
228d0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
228e0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
228f0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
22900 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
22910 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
22920 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
22930 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
22940 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22950 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
22960 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22970 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
22980 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
22990 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
229a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
229b0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
229c0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
229d0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
229e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
229f0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
22a00 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
22a10 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
22a20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
22a30 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
22a40 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
22a50 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
22a60 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
22a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
22a80 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22a90 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
22aa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
22ab0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
22ac0 29 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  ) the number of 
22ad0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
22ae0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
22af0 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
22b00 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
22b10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
22b20 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
22b30 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
22b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22b50 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
22b60 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
22b70 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
22b80 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
22b90 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
22ba0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
22bb0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
22bc0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
22bd0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
22be0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
22bf0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
22c00 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
22c10 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
22c20 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
22c30 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
22c40 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
22c50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
22c60 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
22c70 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
22c80 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
22c90 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
22ca0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
22cb0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
22cc0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
22cd0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
22ce0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
22cf0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
22d00 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
22d10 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
22d20 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
22d30 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
22d40 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
22d50 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
22d60 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
22d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d80 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
22d90 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
22da0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
22db0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
22dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
22dd0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
22de0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
22df0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
22e00 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
22e10 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
22e20 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
22e30 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
22e40 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
22e50 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
22e60 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
22e70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
22e80 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
22e90 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
22ea0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
22eb0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
22ec0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
22ed0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
22ee0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
22ef0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
22f00 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
22f10 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
22f20 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
22f30 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
22f40 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
22f50 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
22f60 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
22f70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22f80 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
22f90 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
22fa0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
22fb0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
22fc0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
22fd0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
22fe0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
22ff0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
23000 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
23010 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
23020 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
23030 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
23040 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
23050 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
23060 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
23070 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
23080 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
23090 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
230a0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
230b0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
230c0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
230d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
230e0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
230f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
23100 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
23110 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
23120 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
23130 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
23140 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
23150 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
23160 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
23170 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
23180 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
23190 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
231a0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
231b0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
231c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
231d0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
231e0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
231f0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
23200 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
23210 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
23220 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
23230 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
23240 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
23250 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
23260 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
23270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23280 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
23290 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
232a0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
232b0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
232c0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
232d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
232e0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
232f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
23300 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
23310 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
23320 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
23330 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
23340 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
23350 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
23360 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
23370 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
23380 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
23390 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
233a0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
233b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
233c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
233d0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
233e0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
233f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
23400 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
23410 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
23420 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
23430 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
23440 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
23450 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
23460 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
23470 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
23480 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
23490 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
234a0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
234b0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
234c0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
234d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
234e0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
234f0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
23500 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
23510 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
23520 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
23530 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
23540 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
23550 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
23560 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
23570 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
23580 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
23590 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
235a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
235b0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
235c0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
235d0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
235e0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
235f0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
23600 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
23610 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
23620 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
23630 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
23640 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
23650 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
23660 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
23670 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
23680 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
23690 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
236a0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
236b0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
236c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
236d0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
236e0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
236f0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
23700 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
23710 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
23720 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
23730 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
23740 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23750 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
23760 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
23770 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
23780 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
23790 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
237a0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
237b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
237c0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
237d0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
237e0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
237f0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
23800 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
23810 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
23820 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
23830 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20  rity: the value 
23840 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
23850 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
23860 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
23870 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
23880 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
23890 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
238a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
238b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
238c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
238d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
238e0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
238f0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
23900 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
23910 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
23920 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
23930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
23940 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
23950 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61  gth BLOB is an a
23960 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e  rbitrary.** poin
23970 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76  ter, possibly ev
23980 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
23990 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
239a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
239b0 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
239c0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
239d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
239e0 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
239f0 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
23a00 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
23a10 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
23a20 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
23a30 20 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69   ^The zero termi
23a40 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63  nator is not inc
23a50 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f  luded in this co
23a60 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  unt..**.** ^The 
23a70 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
23a80 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
23a90 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
23aa0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
23ab0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
23ac0 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
23ad0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23ae0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
23af0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
23b00 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
23b10 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
23b20 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
23b30 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
23b40 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
23b50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23b60 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
23b70 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
23b80 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
23b90 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
23ba0 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
23bb0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
23bc0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
23bd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
23be0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
23bf0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
23c00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
23c10 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
23c20 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
23c30 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
23c40 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
23c50 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
23c60 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
23c70 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
23c80 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
23c90 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
23ca0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
23cb0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
23cc0 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
23cd0 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
23ce0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
23cf0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
23d00 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
23d10 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
23d20 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
23d30 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
23d40 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
23d50 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
23d60 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
23d70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
23d80 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
23d90 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
23da0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
23db0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
23dc0 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
23dd0 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
23de0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
23df0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
23e00 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23e10 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
23e20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
23e30 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
23e40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
23e50 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
23e60 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
23e70 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
23e80 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
23e90 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
23ea0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
23eb0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
23ec0 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
23ed0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
23ee0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
23ef0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
23f00 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
23f10 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
23f20 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
23f30 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
23f40 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
23f50 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
23f60 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
23f70 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
23f80 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
23f90 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
23fa0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
23fb0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
23fc0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
23fd0 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
23fe0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
23ff0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
24000 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
24010 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
24020 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
24030 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
24040 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
24050 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
24060 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
24070 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
24080 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
24090 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
240a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
240b0 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
240c0 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
240d0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
240e0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
240f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
24100 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
24110 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
24120 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
24130 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
24140 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
24150 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
24160 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
24170 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
24180 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
24190 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
241a0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
241b0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
241c0 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
241d0 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
241e0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
241f0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
24200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
24210 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
24220 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
24230 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
24240 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
24250 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
24260 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
24270 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
24280 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
24290 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
242a0 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
242b0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
242c0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
242d0 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
242e0 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
242f0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
24300 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
24310 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
24320 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
24330 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ers..**.** ^Note
24340 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
24350 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
24360 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
24370 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
24380 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
24390 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
243a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
243b0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
243c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
243d0 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
243e0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
243f0 20 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73 69   ^(Type conversi
24400 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
24410 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
24420 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
24430 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
24440 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
24450 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
24460 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
24470 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
24480 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
24490 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
244a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
244b0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
244c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
244d0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
244e0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
244f0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
24500 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
24510 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
24520 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
24530 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
24540 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
24550 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
24560 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
24570 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
24580 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
24590 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
245a0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
245b0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
245c0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
245d0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
245e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
245f0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
24600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24610 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
24620 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
24630 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
24640 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
24650 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
24660 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  )^.**.** ^Conver
24670 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
24680 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
24690 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
246a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
246b0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
246c0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
246d0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
246e0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
246f0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
24700 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
24710 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e  ior pointer poin
24720 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20  ts to will have 
24730 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
24740 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
24750 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
24760 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
24770 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
24780 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
24790 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
247a0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
247b0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
247c0 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
247d0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
247e0 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73 74  .** ^(The safest
247f0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
24800 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
24810 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
24820 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
24830 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
24840 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
24850 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
24860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24870 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
24880 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
24890 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
248a0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
248b0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
248c0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
248d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
248e0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
248f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24900 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
24910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24920 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
24930 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49   </ul>)^.**.** I
24940 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
24950 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
24960 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24970 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
24980 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
24990 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
249a0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
249b0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
249c0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
249d0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
249e0 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
249f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24a00 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
24a10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
24a20 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
24a30 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
24a40 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
24a50 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
24a60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
24a70 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
24a80 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
24a90 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
24aa0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
24ab0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
24ac0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
24ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24ae0 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
24af0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
24b00 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
24b10 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
24b20 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
24b30 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
24b40 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
24b50 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
24b60 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
24b70 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
24b80 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
24b90 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
24ba0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24bb0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
24bc0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
24bd0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
24be0 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
24bf0 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
24c00 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
24c10 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
24c20 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
24c30 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
24c40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
24c50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
24c60 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
24c70 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
24c80 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
24c90 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
24ca0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
24cb0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
24cc0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
24cd0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
24ce0 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
24cf0 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
24d00 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
24d10 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
24d20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
24d30 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
24d40 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
24d50 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
24d60 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
24d70 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
24d80 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
24d90 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
24da0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
24db0 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
24dc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
24dd0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
24de0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24df0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24e00 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
24e10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24e20 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
24e30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
24e40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
24e50 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
24e60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24e70 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
24e80 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24e90 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
24ea0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
24eb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24ec0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
24ed0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
24ee0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
24ef0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
24f00 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
24f10 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
24f20 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
24f30 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24f40 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
24f50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24f60 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
24f70 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
24f80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
24f90 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
24fa0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24fb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
24fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
24fd0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
24fe0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
24ff0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
25000 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
25010 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
25020 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
25030 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25040 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
25050 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
25060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25070 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
25080 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65   statement was e
25090 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66  xecuted successf
250a0 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63  ully or not exec
250b0 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
250c0 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69  n.** SQLITE_OK i
250d0 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20  s returned. ^If 
250e0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
250f0 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
25100 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72  d then an.** [er
25110 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ror code] or [ex
25120 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
25130 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
25140 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
25150 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
25160 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
25170 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  uring the execut
25180 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  ion of the.** [p
25190 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
251a0 74 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69 72  t].  ^If the vir
251b0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73  tual machine has
251c0 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   not.** complete
251d0 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e  d execution when
251e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
251f0 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73   called, that is
25200 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74   like.** encount
25210 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f  ering an error o
25220 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  r an [sqlite3_in
25230 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
25240 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70  upt]..** ^Incomp
25250 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
25260 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
25270 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
25280 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65   canceled,.** de
25290 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
252a0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
252b0 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20  d the.** [error 
252c0 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
252d0 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
252e0 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  BORT]..*/.int sq
252f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
25300 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
25310 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
25320 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
25330 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
25340 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
25350 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
25360 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
25370 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
25380 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25390 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
253a0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
253b0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
253c0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
253d0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
253e0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
253f0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
25400 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
25410 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
25420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25430 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
25440 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
25450 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
25460 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
25470 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
25480 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
25490 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
254a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
254b0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
254c0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
254d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
254e0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
254f0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
25500 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
25510 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
25520 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
25530 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
25540 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
25550 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25560 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
25570 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
25580 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
25590 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
255a0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
255b0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
255c0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
255d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
255e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
255f0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
25600 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
25610 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25620 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
25630 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
25640 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
25650 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
25660 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
25670 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
25680 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
25690 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
256a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
256b0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
256c0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
256d0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
256e0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
256f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
25700 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
25710 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25720 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
25730 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
25740 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
25750 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25760 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
25770 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
25780 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
25790 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
257a0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
257b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
257c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
257d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
257e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
257f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25800 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
25810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77  .**.** ^These tw
25820 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
25830 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
25840 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
25850 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
25860 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
25870 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
25880 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
25890 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
258a0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
258b0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
258c0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
258d0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
258e0 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  y difference bet
258f0 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20  ween the.** two 
25900 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
25910 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
25920 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73  e name of the (s
25930 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20  calar) function 
25940 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c  or.** aggregate,
25950 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
25960 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33  TF-8 for sqlite3
25970 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25980 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a  () and UTF-16.**
25990 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
259a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
259b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
259c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
259d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
259e0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
259f0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
25a00 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
25a10 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
25a20 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
25a30 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
25a40 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
25a50 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
25a60 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25a70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
25a80 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
25a90 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
25aa0 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
25ab0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
25ac0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
25ad0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
25ae0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
25af0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
25b00 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
25b10 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
25b20 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
25b30 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
25b40 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a   exclusive of.**
25b50 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
25b60 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
25b70 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
25b80 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
25b90 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
25ba0 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74  cters.  ^Any att
25bb0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
25bc0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
25bd0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
25be0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
25bf0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65  SQLITE_ERROR] be
25c00 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
25c10 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
25c20 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
25c30 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
25c40 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
25c50 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
25c60 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
25c70 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
25c80 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
25c90 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
25ca0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
25cb0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
25cc0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
25cd0 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
25ce0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
25cf0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
25d00 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
25d10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
25d20 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
25d30 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
25d40 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
25d50 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
25d60 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
25d70 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
25d80 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
25d90 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
25da0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
25db0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
25dc0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
25dd0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
25de0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
25df0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
25e00 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
25e10 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
25e20 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
25e30 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
25e40 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
25e50 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
25e60 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
25e70 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
25e80 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25e90 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
25ea0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
25eb0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
25ec0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
25ed0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
25ee0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
25ef0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25f00 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
25f10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
25f20 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
25f30 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
25f40 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
25f50 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
25f60 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
25f70 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
25f80 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
25f90 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
25fa0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
25fb0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
25fc0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
25fd0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
25fe0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
25ff0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
26000 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
26010 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
26020 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
26030 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
26040 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
26050 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
26060 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
26070 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
26080 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
26090 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
260a0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
260b0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
260c0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
260d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
260e0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
260f0 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
26100 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
26110 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
26120 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
26130 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  )^.**.** The sev
26140 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
26150 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
26160 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
26170 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
26180 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
26190 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
261a0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
261b0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
261c0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
261d0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
261e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
261f0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
26200 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
26210 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
26220 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
26230 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
26240 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
26250 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
26260 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
26270 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
26280 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
26290 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
262a0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
262b0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
262c0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
262d0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
262e0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
262f0 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
26300 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
26310 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72  e, pass NULL for
26320 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
26330 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  ion callbacks..*
26340 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
26350 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
26360 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
26370 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
26380 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
26390 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
263a0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
263b0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
263c0 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
263d0 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
263e0 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
263f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
26400 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
26410 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
26420 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
26430 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
26440 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
26450 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
26460 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
26470 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
26480 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
26490 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
264a0 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
264b0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
264c0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
264d0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
264e0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
264f0 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
26500 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
26510 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
26520 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
26530 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
26540 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
26550 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
26560 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
26570 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
26580 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
26590 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
265a0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
265b0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
265c0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
265d0 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
265e0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
265f0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
26600 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
26610 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
26620 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
26630 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
26640 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
26650 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
26660 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
26670 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
26680 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26690 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  s..** ^The first
266a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
266b0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69  ined function wi
266c0 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20  th a given name 
266d0 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a  overrides all.**
266e0 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69   built-in functi
266f0 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20  ons in the same 
26700 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26710 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73  tion] with the s
26720 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75  ame name..** ^Su
26730 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61  bsequent applica
26740 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26750 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ctions of the sa
26760 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65  me name only ove
26770 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20  rride .** prior 
26780 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26790 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ned functions th
267a0 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20  at are an exact 
267b0 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a  match for the.**
267c0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
267d0 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72  eters and prefer
267e0 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  red encoding..**
267f0 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
26800 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26810 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
26820 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
26830 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
26840 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
26850 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
26860 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
26870 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26880 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
26890 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
268a0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
268b0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
268c0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
268d0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
268e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
268f0 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
26900 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
26910 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
26920 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
26930 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
26940 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
26950 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
26960 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
26970 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
26980 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
26990 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
269a0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
269b0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
269c0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
269d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
269e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
269f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
26a00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
26a10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
26a20 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
26a30 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
26a40 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
26a50 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
26a60 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
26a70 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
26a80 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
26a90 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
26aa0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
26ab0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
26ac0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
26ad0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
26ae0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
26af0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
26b00 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
26b10 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
26b20 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
26b30 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
26b40 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
26b50 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
26b60 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
26b70 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
26b80 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
26b90 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
26ba0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
26bb0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
26bc0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
26bd0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
26be0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
26bf0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
26c00 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
26c10 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
26c20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
26c30 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
26c40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26c50 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
26c60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
26c70 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
26c80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
26c90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
26ca0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
26cb0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
26cc0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
26cd0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
26ce0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
26cf0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
26d00 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
26d10 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
26d20 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
26d30 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
26d40 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
26d50 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
26d60 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
26d70 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
26d80 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
26d90 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
26da0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
26db0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
26dc0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
26dd0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
26de0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
26df0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
26e00 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
26e10 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
26e20 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
26e30 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
26e40 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
26e50 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
26e60 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
26e70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26e80 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
26e90 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
26ea0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
26eb0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
26ec0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
26ed0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
26ee0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
26ef0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
26f00 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
26f10 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
26f20 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
26f30 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
26f40 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
26f50 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
26f60 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
26f70 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
26f80 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
26f90 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
26fa0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
26fb0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
26fc0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
26fd0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
26fe0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
26ff0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
27000 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
27010 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
27020 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
27030 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
27040 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
27050 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
27060 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
27070 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
27080 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
27090 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
270a0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
270b0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
270c0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
270d0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
270e0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
270f0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
27100 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
27110 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27120 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
27130 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27140 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
27150 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
27160 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
27170 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
27180 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
27190 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
271a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
271b0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
271c0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
271d0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
271e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
271f0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
27200 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
27210 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
27220 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
27230 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
27240 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
27250 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
27260 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
27270 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
27280 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
27290 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
272a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
272b0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
272c0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
272d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
272e0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
272f0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
27300 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
27310 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
27320 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
27330 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
27340 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
27350 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
27360 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
27370 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
27380 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
27390 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
273a0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
273b0 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
273c0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
273d0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
273e0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
273f0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
27400 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
27410 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
27420 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
27430 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
27440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27450 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
27460 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
27470 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
27480 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
27490 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
274a0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
274b0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
274c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
274d0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
274e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
274f0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
27500 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
27510 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
27520 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
27530 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
27540 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
27550 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
27560 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
27570 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
27580 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
27590 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
275a0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
275b0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
275c0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
275d0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
275e0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
275f0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
27600 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
27610 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
27620 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
27630 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
27640 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
27650 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
27660 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
27670 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
27680 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
27690 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
276a0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
276b0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
276c0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
276d0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
276e0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
276f0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
27700 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
27710 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
27720 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
27730 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
27740 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
27750 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
27760 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
27770 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27780 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
27790 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
277a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
277b0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
277c0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
277d0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
277e0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
277f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
27800 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
27810 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
27820 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
27830 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
27840 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
27850 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
27860 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
27870 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
27880 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
27890 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
278a0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
278b0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
278c0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
278d0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
278e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
278f0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
27900 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
27910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
27920 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
27930 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
27940 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
27950 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27960 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
27970 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
27980 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
27990 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
279a0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
279b0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
279c0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
279d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
279e0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
279f0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
27a00 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
27a10 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27a20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27a30 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27a40 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
27a50 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
27a60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27a70 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
27a80 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
27a90 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
27aa0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
27ab0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
27ac0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
27ad0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
27ae0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
27af0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
27b00 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
27b10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27b20 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
27b30 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
27b40 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
27b50 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  mentions of aggr
27b60 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
27b70 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
27b80 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
27b90 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
27ba0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
27bb0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
27bc0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
27bd0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27be0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
27bf0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
27c00 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
27c10 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
27c20 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
27c30 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
27c40 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
27c50 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
27c60 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
27c70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
27c80 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
27c90 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
27ca0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
27cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
27cc0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
27cd0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
27ce0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
27cf0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
27d00 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
27d10 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
27d20 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
27d30 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
27d40 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
27d50 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
27d60 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
27d70 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
27d80 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
27d90 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
27da0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
27db0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
27dc0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
27dd0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
27de0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
27df0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
27e00 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
27e10 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
27e20 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
27e30 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
27e40 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
27e50 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
27e60 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
27e70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27e80 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
27e90 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
27ea0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
27eb0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
27ec0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
27ed0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
27ee0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
27ef0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
27f00 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
27f10 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
27f20 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
27f30 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
27f40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
27f50 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
27f60 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
27f70 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
27f80 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
27f90 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27fa0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
27fb0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
27fc0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
27fd0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
27fe0 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
27ff0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
28000 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
28010 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
28020 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28030 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
28040 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
28050 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
28060 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
28070 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
28080 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
28090 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
280a0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
280b0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
280c0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
280d0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
280e0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
280f0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
28100 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
28110 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
28120 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
28130 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
28140 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
28150 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
28160 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
28170 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
28180 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
28190 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
281a0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
281b0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
281c0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
281d0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
281e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
281f0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
28200 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
28210 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
28220 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
28230 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
28240 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
28250 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28260 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
28270 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
28280 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
28290 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
282a0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
282b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
282c0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
282d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
282e0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
282f0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
28300 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
28310 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
28320 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
28330 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
28340 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28350 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
28360 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28370 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
28380 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
28390 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
283a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
283b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
283c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
283d0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
283e0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
283f0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
28400 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
28410 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28420 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
28430 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
28440 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
28450 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
28460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28470 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
28480 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
28490 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
284a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
284b0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
284c0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
284d0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
284e0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
284f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28500 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
28510 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
28520 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
28530 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
28540 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
28550 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
28560 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
28570 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
28580 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
28590 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
285a0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
285b0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
285c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
285d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
285e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
285f0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
28600 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
28610 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
28620 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
28630 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
28640 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
28650 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
28660 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
28670 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
28680 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
28690 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
286a0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
286b0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
286c0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
286d0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
286e0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
286f0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
28700 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
28710 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
28720 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
28730 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
28740 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
28750 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
28760 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
28770 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
28780 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
28790 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
287a0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
287b0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
287c0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
287d0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
287e0 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
287f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
28800 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
28810 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
28820 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
28830 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
28840 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
28850 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
28860 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
28870 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
28880 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
28890 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
288a0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
288b0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
288c0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
288d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
288e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
288f0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
28900 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
28910 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
28920 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
28930 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
28940 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
28950 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
28960 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
28970 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
28980 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28990 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
289a0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
289b0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
289c0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
289d0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
289e0 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
289f0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
28a00 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
28a10 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
28a20 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
28a30 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
28a40 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
28a50 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
28a60 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
28a70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
28a80 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
28a90 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
28aa0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
28ab0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
28ac0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
28ad0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
28ae0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
28af0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
28b00 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
28b10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28b20 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
28b30 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
28b40 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
28b50 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
28b60 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
28b70 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
28b80 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
28b90 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
28ba0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
28bb0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
28bc0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
28bd0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
28be0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
28bf0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
28c00 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
28c10 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
28c20 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
28c30 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
28c40 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
28c50 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
28c60 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
28c70 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
28c80 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
28c90 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
28ca0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
28cb0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
28cc0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
28cd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
28ce0 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
28cf0 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
28d00 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
28d10 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
28d20 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
28d30 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
28d40 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
28d50 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
28d60 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
28d70 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
28d80 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
28d90 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
28da0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
28db0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
28dc0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
28dd0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
28de0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
28df0 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
28e00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
28e10 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
28e20 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
28e30 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
28e40 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
28e50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
28e60 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
28e70 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
28e80 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
28e90 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
28ea0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
28eb0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
28ec0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
28ed0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
28ee0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
28ef0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
28f00 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
28f10 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
28f20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
28f30 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
28f40 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
28f50 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
28f60 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
28f70 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
28f80 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
28f90 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
28fa0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
28fb0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
28fc0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
28fd0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
28fe0 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
28ff0 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
29000 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
29010 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
29020 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
29030 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
29040 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
29050 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
29060 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
29070 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
29080 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
29090 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
290a0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
290b0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
290c0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
290d0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
290e0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
290f0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
29100 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
29110 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
29120 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
29130 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
29140 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
29150 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
29160 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
29170 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
29180 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
29190 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
291a0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
291b0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
291c0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
291d0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
291e0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
291f0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
29200 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
29210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
29220 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
29230 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
29240 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
29250 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
29260 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
29270 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
29280 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
29290 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
292a0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
292b0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
292c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
292d0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
292e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
292f0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
29300 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
29310 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
29320 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
29330 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
29340 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
29350 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
29360 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
29370 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
29380 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
29390 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
293a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
293b0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
293c0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
293d0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
293e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
293f0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
29400 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29410 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
29420 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
29430 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
29440 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
29450 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
29460 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
29470 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
29480 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
29490 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
294a0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
294b0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
294c0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
294d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
294e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
294f0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
29500 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
29510 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
29520 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
29530 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29540 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
29550 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
29560 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
29570 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
29580 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
29590 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
295a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
295b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
295c0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
295d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
295e0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
295f0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
29600 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29610 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
29620 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
29630 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
29640 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
29650 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
29660 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29670 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
29680 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
29690 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
296a0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
296b0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
296c0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
296d0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
296e0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
296f0 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
29700 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
29710 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
29720 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
29730 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
29740 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
29750 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
29760 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
29770 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
29780 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
29790 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
297a0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
297b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
297c0 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
297d0 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
297e0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
297f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29800 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
29810 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
29820 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
29830 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
29840 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
29850 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
29860 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
29870 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
29880 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
29890 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
298a0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
298b0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
298c0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
298d0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
298e0 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
298f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29900 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29910 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
29920 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29930 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
29940 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
29950 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
29960 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
29970 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
29980 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
29990 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
299a0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
299b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
299c0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
299d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
299e0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
299f0 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
29a00 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
29a10 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
29a20 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
29a30 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
29a40 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
29a50 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
29a60 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
29a70 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
29a80 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
29a90 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
29aa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29ab0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
29ac0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
29ad0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
29ae0 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
29af0 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
29b00 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
29b10 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
29b20 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
29b30 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
29b40 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
29b50 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
29b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29b70 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
29b80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29b90 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
29ba0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
29bb0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
29bc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
29bd0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
29be0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
29bf0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
29c00 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
29c10 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
29c20 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
29c30 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
29c40 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
29c50 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29c60 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
29c70 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
29c80 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
29c90 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
29ca0 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
29cb0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
29cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29cd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
29ce0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
29cf0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
29d00 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
29d10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29d20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
29d30 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
29d40 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
29d50 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
29d60 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
29d70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29d80 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
29d90 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
29da0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
29db0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
29dc0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29dd0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
29de0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
29df0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
29e00 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
29e10 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
29e20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29e30 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
29e40 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
29e50 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
29e60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
29e70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
29e80 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
29e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29ea0 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
29eb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
29ec0 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
29ed0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
29ee0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
29ef0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
29f00 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
29f10 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
29f20 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
29f30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29f40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
29f50 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
29f60 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
29f70 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
29f80 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
29f90 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
29fa0 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
29fb0 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
29fc0 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
29fd0 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
29fe0 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
29ff0 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
2a000 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
2a010 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
2a020 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
2a030 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a040 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
2a050 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
2a060 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2a070 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a080 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2a090 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2a0a0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2a0b0 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
2a0c0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2a0d0 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
2a0e0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2a0f0 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
2a100 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2a110 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2a120 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2a130 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
2a140 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
2a150 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
2a160 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2a170 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
2a180 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2a190 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2a1a0 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
2a1b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a1c0 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
2a1d0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2a1e0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2a1f0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2a200 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2a210 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2a220 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2a230 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
2a240 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
2a250 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
2a260 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
2a270 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
2a280 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
2a290 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
2a2a0 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
2a2b0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2a2c0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
2a2d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2a2e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2a2f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2a300 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
2a310 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2a320 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2a330 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2a340 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
2a350 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
2a360 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
2a370 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
2a380 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
2a390 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
2a3a0 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
2a3b0 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
2a3c0 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
2a3d0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
2a3e0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
2a3f0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2a400 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2a410 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
2a420 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2a430 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a440 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2a450 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2a460 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2a470 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
2a480 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
2a490 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
2a4a0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
2a4b0 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
2a4c0 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
2a4d0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
2a4e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2a4f0 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
2a500 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2a510 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2a520 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
2a530 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2a540 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
2a550 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a560 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2a570 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
2a580 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2a590 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a5a0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2a5b0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
2a5c0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2a5d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2a5e0 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
2a5f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
2a600 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2a610 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73  * so that the [s
2a620 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70  qlite3_value] sp
2a630 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70  ecified in the p
2a640 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61  arameter may cha
2a650 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61  nge or.** be dea
2a660 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73  llocated after s
2a670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2a680 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69  lue() returns wi
2a690 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
2a6a0 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
2a6b0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a6c0 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
2a6d0 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
2a6e0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2a6f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a700 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
2a710 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
2a720 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
2a730 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
2a740 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
2a750 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
2a760 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
2a770 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2a780 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
2a790 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
2a7a0 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
2a7b0 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
2a7c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2a7d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2a7e0 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
2a7f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
2a800 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
2a810 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2a820 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69  ndefined..*/.voi
2a830 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a840 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
2a850 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2a860 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2a870 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2a880 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
2a890 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
2a8a0 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
2a8b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a8c0 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
2a8d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2a8e0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
2a8f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a900 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
2a910 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2a920 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
2a930 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a940 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
2a950 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
2a960 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2a970 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
2a980 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
2a990 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2a9a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a9b0 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
2a9c0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
2a9d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a9e0 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
2a9f0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
2aa00 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2aa10 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
2aa20 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2aa30 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
2aa40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2aa50 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
2aa60 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2aa70 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2aa80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2aa90 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2aaa0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2aab0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2aac0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2aad0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2aae0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2aaf0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2ab00 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2ab10 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2ab20 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2ab30 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2ab40 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
2ab50 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2ab60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2ab70 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
2ab80 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2ab90 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2aba0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2abb0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2abc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2abd0 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
2abe0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2abf0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
2ac00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ac10 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
2ac20 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
2ac30 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
2ac40 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a   Sequences.**.**
2ac50 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
2ac60 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
2ac70 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
2ac80 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a  equences to the.
2ac90 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
2aca0 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
2acb0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2acc0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2acd0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2ace0 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   new collation s
2acf0 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69  equence is speci
2ad00 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20  fied as a UTF-8 
2ad10 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
2ad20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2ad30 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
2ad40 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2ad50 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
2ad60 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
2ad70 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  g for sqlite3_cr
2ad80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2ad90 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65  (). ^In all case
2ada0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73  s.** the name is
2adb0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
2adc0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2add0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2ade0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2adf0 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nt may be one of
2ae00 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b   the constants [
2ae10 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
2ae20 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2ae30 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ], or [SQLITE_UT
2ae40 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16BE], indicati
2ae50 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72  ng that the user
2ae60 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75  -supplied.** rou
2ae70 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20  tine expects to 
2ae80 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65  be passed pointe
2ae90 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e  rs to strings en
2aea0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
2aeb0 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  8,.** UTF-16 lit
2aec0 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle-endian, or U
2aed0 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
2aee0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
2aef0 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72  ^The.** third ar
2af00 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
2af10 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
2af20 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20  16] to indicate 
2af30 74 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65  that the routine
2af40 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e  .** expects poin
2af50 74 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31  ters to be UTF-1
2af60 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  6 strings in the
2af70 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2af80 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72  er, or the.** ar
2af90 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53  gument can be [S
2afa0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2afb0 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74  NED] if the.** t
2afc0 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  he routine expec
2afd0 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31  ts pointers to 1
2afe0 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e  6-bit word align
2aff0 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66  ed strings.** of
2b000 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
2b010 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2b020 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
2b030 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
2b040 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
2b050 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2b060 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
2b070 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20  gument.  ^If it 
2b080 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73  is NULL, this is
2b090 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c   the same as del
2b0a0 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74  eting the collat
2b0b0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2b0c0 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20  (so that SQLite 
2b0d0 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61  cannot call it a
2b0e0 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63  nymore)..** ^Eac
2b0f0 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69  h time the appli
2b100 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20  cation supplied 
2b110 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
2b120 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65  ked, it is passe
2b130 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73  d.** as its firs
2b140 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f  t parameter a co
2b150 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
2b160 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
2b170 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  urth argument.**
2b180 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
2b190 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f  te_collation() o
2b1a0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2b1b0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
2b1c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69  **.** ^The remai
2b1d0 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74  ning arguments t
2b1e0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
2b1f0 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  n-supplied routi
2b200 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e  ne are two strin
2b210 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72  gs,.** each repr
2b220 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65  esented by a (le
2b230 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72  ngth, data) pair
2b240 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20   and encoded in 
2b250 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  the encoding.** 
2b260 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
2b270 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  as the third arg
2b280 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63  ument when the c
2b290 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2b2a0 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65  e was.** registe
2b2b0 72 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69 63  red.  The applic
2b2c0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
2b2d0 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
2b2e0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
2b2f0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
2b300 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74  or positive if t
2b310 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
2b320 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a  is less than,.**
2b330 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
2b340 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
2b350 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e  econd string. i.
2b360 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
2b370 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  RING2)..**.** ^T
2b380 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
2b390 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2b3a0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
2b3b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b3c0 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  tion().** except
2b3d0 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61   that it takes a
2b3e0 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74  n extra argument
2b3f0 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74   which is a dest
2b400 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68  ructor for.** th
2b410 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54  e collation.  ^T
2b420 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2b430 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2b440 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a   collation is.**
2b450 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69   destroyed and i
2b460 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79 20  s passed a copy 
2b470 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2b480 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f  rameter void* po
2b490 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20  inter.** of the 
2b4a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b4b0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a  ollation_v2()..*
2b4c0 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72  * ^Collations ar
2b4d0 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e  e destroyed when
2b4e0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
2b4f0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61  dden by later ca
2b500 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f  lls to the.** co
2b510 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
2b520 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
2b530 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  en the [database
2b540 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
2b550 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20  closed.** using 
2b560 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2b570 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2b580 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
2b590 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
2b5a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2b5b0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2b5c0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2b5d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b5e0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
2b5f0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2b600 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2b610 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2b620 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2b630 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2b640 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2b650 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
2b660 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2b670 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
2b680 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
2b690 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2b6a0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
2b6b0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
2b6c0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2b6d0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b6e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2b6f0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
2b700 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2b710 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2b720 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2b730 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2b740 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
2b750 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
2b760 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2b770 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2b780 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2b790 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2b7a0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
2b7b0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
2b7c0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
2b7d0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
2b7e0 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
2b7f0 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
2b800 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
2b810 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
2b820 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
2b830 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
2b840 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
2b850 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
2b860 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
2b870 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b880 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2b890 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
2b8a0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
2b8b0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
2b8c0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
2b8d0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2b8e0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
2b8f0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
2b900 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2b910 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
2b920 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
2b930 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
2b940 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2b950 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
2b960 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
2b970 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
2b980 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2b990 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
2b9a0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
2b9b0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
2b9c0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
2b9d0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
2b9e0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
2b9f0 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
2ba00 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
2ba10 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
2ba20 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
2ba30 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
2ba40 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2ba50 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
2ba60 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
2ba70 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
2ba80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2ba90 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
2baa0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2bab0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2bac0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2bad0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
2bae0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2baf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2bb00 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
2bb10 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2bb20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
2bb30 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2bb40 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
2bb50 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
2bb60 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
2bb70 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
2bb80 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
2bb90 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2bba0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2bbb0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
2bbc0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2bbd0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
2bbe0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
2bbf0 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
2bc00 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2bc10 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
2bc20 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
2bc30 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
2bc40 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2bc50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2bc60 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
2bc70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2bc80 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
2bc90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2bca0 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
2bcb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2bcc0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
2bcd0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2bce0 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
2bcf0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
2bd00 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
2bd10 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
2bd20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2bd30 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
2bd40 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
2bd50 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
2bd60 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
2bd70 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
2bd80 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
2bd90 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
2bda0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2bdb0 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
2bdc0 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
2bdd0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
2bde0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
2bdf0 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
2be00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
2be10 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
2be20 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
2be30 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
2be40 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
2be50 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
2be60 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
2be70 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20   sqlite3_key(.  
2be80 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2be90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2bea0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2beb0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2bec0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2bed0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2bee0 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f  The key */.);../
2bef0 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20  *.** Change the 
2bf00 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64  key on an open d
2bf10 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65  atabase.  If the
2bf20 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73   current databas
2bf30 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72  e is not.** encr
2bf40 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74  ypted, this rout
2bf50 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74  ine will encrypt
2bf60 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30   it.  If pNew==0
2bf70 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65   or nNew==0, the
2bf80 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20  .** database is 
2bf90 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a  decrypted..**.**
2bfa0 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70   The code to imp
2bfb0 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20  lement this API 
2bfc0 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65  is not available
2bfd0 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72   in the public r
2bfe0 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c  elease.** of SQL
2bff0 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
2c000 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c  te3_rekey(.  sql
2c010 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c020 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2c030 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
2c040 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
2c050 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
2c060 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
2c070 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   new key */.);..
2c080 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2c090 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
2c0a0 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62   for a SEE datab
2c0b0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
2c0c0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
2c0d0 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74   of the SEE rout
2c0e0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
2c0f0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2c100 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20  activate_see(.  
2c110 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
2c120 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
2c130 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
2c140 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
2c150 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  ..#ifdef SQLITE_
2c160 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a  ENABLE_CEROD./*.
2c170 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61  ** Specify the a
2c180 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f  ctivation key fo
2c190 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61  r a CEROD databa
2c1a0 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20  se.  Unless .** 
2c1b0 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20  activated, none 
2c1c0 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75  of the CEROD rou
2c1d0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
2c1e0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2c1f0 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28  _activate_cerod(
2c200 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2c210 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
2c220 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
2c230 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
2c240 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2c250 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
2c260 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
2c270 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e 54  rt Time.**.** ^T
2c280 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
2c290 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
2c2a0 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
2c2b0 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
2c2c0 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
2c2d0 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
2c2e0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
2c2f0 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
2c300 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
2c310 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  **.** ^If the op
2c320 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
2c330 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
2c340 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
2c350 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
2c360 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
2c370 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
2c380 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
2c390 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
2c3a0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 5e  earest second. ^
2c3b0 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  The number of mi
2c3c0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
2c3d0 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20  eep actually.** 
2c3e0 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74  requested from t
2c3f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2c400 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  tem is returned.
2c410 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69  .**.** ^SQLite i
2c420 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69  mplements this i
2c430 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c  nterface by call
2c440 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29  ing the xSleep()
2c450 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  .** method of th
2c460 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
2c470 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
2c480 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2c490 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  leep(int);../*.*
2c4a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2c4b0 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48   Of The Folder H
2c4c0 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79  olding Temporary
2c4d0 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49   Files.**.** ^(I
2c4e0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61  f this global va
2c4f0 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74  riable is made t
2c500 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  o point to a str
2c510 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20  ing which is.** 
2c520 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f  the name of a fo
2c530 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72  lder (a.k.a. dir
2c540 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c  ectory), then al
2c550 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  l temporary file
2c560 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  s.** created by 
2c570 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e  SQLite when usin
2c580 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71  g a built-in [sq
2c590 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d  lite3_vfs | VFS]
2c5a0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  .** will be plac
2c5b0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
2c5c0 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69  tory.)^  ^If thi
2c5d0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73  s variable.** is
2c5e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
2c5f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72   then SQLite per
2c600 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66  forms a search f
2c610 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
2c620 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
2c630 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ile directory..*
2c640 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
2c650 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2c660 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2c670 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
2c680 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
2c690 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
2c6a0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
2c6b0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
2c6c0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
2c6d0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
2c6e0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
2c6f0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
2c700 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
2c710 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
2c720 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
2c730 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
2c740 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
2c750 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
2c760 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
2c770 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
2c780 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
2c790 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
2c7a0 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
2c7b0 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
2c7c0 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
2c7d0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
2c7e0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
2c7f0 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65  ^The [temp_store
2c800 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2c810 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
2c820 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
2c830 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
2c840 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2c850 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2c860 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
2c870 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
2c880 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
2c890 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2c8a0 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
2c8b0 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
2c8c0 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
2c8d0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
2c8e0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
2c8f0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2c900 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
2c910 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
2c920 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
2c930 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
2c940 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
2c950 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
2c960 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
2c970 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
2c980 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
2c990 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
2c9a0 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
2c9b0 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
2c9c0 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
2c9d0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
2c9e0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
2c9f0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
2ca00 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65   the [temp_store
2ca10 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
2ca20 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
2ca30 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
2ca40 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
2ca50 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
2ca60 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
2ca70 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
2ca80 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
2ca90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
2caa0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
2cab0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cac0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
2cad0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2cae0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
2caf0 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
2cb00 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
2cb10 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
2cb20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
2cb30 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
2cb40 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75  spectively.  ^Au
2cb50 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2cb60 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
2cb70 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
2cb80 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
2cb90 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
2cba0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f  tement..** ^Auto
2cbb0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
2cbc0 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
2cbd0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
2cbe0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
2cbf0 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
2cc00 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
2cc10 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
2cc20 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
2cc30 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
2cc40 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
2cc50 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
2cc60 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
2cc70 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
2cc80 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
2cc90 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
2cca0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
2ccb0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
2ccc0 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
2ccd0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
2cce0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
2ccf0 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
2cd00 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
2cd10 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
2cd20 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2cd30 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2cd40 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
2cd50 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
2cd60 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
2cd70 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
2cd80 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
2cd90 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
2cda0 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
2cdb0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2cdc0 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
2cdd0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
2cde0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
2cdf0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
2ce00 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
2ce10 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
2ce20 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
2ce30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ce40 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
2ce50 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
2ce60 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2ce70 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2ce80 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
2ce90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2cea0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ceb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2cec0 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
2ced0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cee0 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e  ent] belongs.  ^
2cef0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
2cf00 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
2cf10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2cf20 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
2cf30 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
2cf40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
2cf50 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
2cf60 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
2cf70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
2cf80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
2cf90 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
2cfa0 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
2cfb0 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
2cfc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
2cfd0 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
2cfe0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2cff0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
2d000 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2d010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d020 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72  Find the next pr
2d030 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d040 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
2d050 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2d060 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d070 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
2d080 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
2d090 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
2d0a0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
2d0b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d0c0 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74  n] pDb.  ^If pSt
2d0d0 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  mt is NULL.** th
2d0e0 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  en this interfac
2d0f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2d100 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74  ter to the first
2d110 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d120 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ent.** associate
2d130 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62  d with the datab
2d140 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70  ase connection p
2d150 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70  Db.  ^If no prep
2d160 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2d170 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20  * satisfies the 
2d180 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68  conditions of th
2d190 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72  is routine, it r
2d1a0 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  eturns NULL..**.
2d1b0 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  ** The [database
2d1c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69   connection] poi
2d1d0 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c  nter D in a call
2d1e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d1f0 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20  next_stmt(D,S)] 
2d200 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e  must refer to an
2d210 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a   open database.*
2d220 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64  * connection and
2d230 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d   in particular m
2d240 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c  ust not be a NUL
2d250 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
2d260 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69  lite3_stmt *sqli
2d270 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71  te3_next_stmt(sq
2d280 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69  lite3 *pDb, sqli
2d290 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d2a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d2b0 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f  F: Commit And Ro
2d2c0 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74  llback Notificat
2d2d0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
2d2e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d2f0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69  _commit_hook() i
2d300 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2d310 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2d320 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2d330 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2d340 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2d350 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d  s [COMMIT | comm
2d360 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20  itted]..** ^Any 
2d370 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
2d380 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
2d390 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  to sqlite3_commi
2d3a0 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  t_hook().** for 
2d3b0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2d3c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2d3d0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
2d3e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  The sqlite3_roll
2d3f0 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  back_hook() inte
2d400 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
2d410 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
2d420 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
2d430 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2d440 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
2d450 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65  ROLLBACK | rolle
2d460 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79  d back]..** ^Any
2d470 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2d480 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2d490 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c   to sqlite3_roll
2d4a0 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  back_hook().** f
2d4b0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2d4c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d4d0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2d4e0 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75  * ^The pArg argu
2d4f0 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74  ment is passed t
2d500 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61  hrough to the ca
2d510 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74  llback..** ^If t
2d520 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61  he callback on a
2d530 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e   commit hook fun
2d540 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
2d550 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  n-zero,.** then 
2d560 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f  the commit is co
2d570 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72  nverted into a r
2d580 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
2d590 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  The sqlite3_comm
2d5a0 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61  it_hook(D,C,P) a
2d5b0 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  nd sqlite3_rollb
2d5c0 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ack_hook(D,C,P) 
2d5d0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74  functions.** ret
2d5e0 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65  urn the P argume
2d5f0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
2d600 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65  ious call of the
2d610 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a   same function.*
2d620 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
2d630 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d640 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
2d650 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
2d660 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75  call for each fu
2d670 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a  nction on D..**.
2d680 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
2d690 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
2d6a0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
2d6b0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
2d6c0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
2d6d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d6e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
2d6f0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20   callback.  Any 
2d700 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
2d710 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
2d720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
2d730 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
2d740 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
2d750 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
2d760 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
2d770 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
2d780 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d  iggered the comm
2d790 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63  it.** or rollbac
2d7a0 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69  k hook in the fi
2d7b0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f  rst place..** No
2d7c0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2d7d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2d7e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2d7f0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2d800 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2d810 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2d820 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2d830 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2d840 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2d850 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20  ** ^Registering 
2d860 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
2d870 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
2d880 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  lback..**.** ^Wh
2d890 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
2d8a0 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
2d8b0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
2d8c0 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
2d8d0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
2d8e0 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
2d8f0 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49  ue normally.  ^I
2d900 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
2d910 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
2d920 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
2d930 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
2d940 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
2d950 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65  LLBACK]..** ^The
2d960 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
2d970 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72  s invoked on a r
2d980 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73  ollback that res
2d990 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d  ults from a comm
2d9a0 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72  it.** hook retur
2d9b0 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a  ning non-zero, j
2d9c0 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20  ust as it would 
2d9d0 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65  be with any othe
2d9e0 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  r rollback..**.*
2d9f0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
2da00 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
2da10 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2da20 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
2da30 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
2da40 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
2da50 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
2da60 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
2da70 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
2da80 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
2da90 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
2daa0 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
2dab0 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72  occur..** ^The r
2dac0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
2dad0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
2dae0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
2daf0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
2db00 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2db10 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
2db20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2db30 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
2db40 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2db50 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2db60 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
2db70 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2db80 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
2db90 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
2dba0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
2dbb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
2dbc0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
2dbd0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
2dbe0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
2dbf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dc00 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
2dc10 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
2dc20 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
2dc30 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2dc40 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2dc50 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2dc60 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
2dc70 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2dc80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
2dc90 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
2dca0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2dcb0 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
2dcc0 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
2dcd0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2dce0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2dcf0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
2dd00 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2dd10 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
2dd20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
2dd30 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2dd40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2dd50 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
2dd60 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
2dd70 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2dd80 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
2dd90 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
2dda0 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
2ddb0 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
2ddc0 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
2ddd0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2dde0 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
2ddf0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
2de00 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
2de10 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
2de20 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
2de30 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2de40 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  callback argumen
2de50 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
2de60 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
2de70 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a  LITE_DELETE],.**
2de80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
2de90 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  TE], depending o
2dea0 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
2deb0 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
2dec0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62  callback.** to b
2ded0 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  e invoked..** ^T
2dee0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2def0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
2df00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
2df10 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
2df20 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
2df30 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
2df40 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2df50 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
2df60 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c   ^The final call
2df70 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
2df80 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
2df90 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e   the row..** ^In
2dfa0 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
2dfb0 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
2dfc0 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
2dfd0 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
2dfe0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
2dff0 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  ^(The update hoo
2e000 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2e010 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
2e020 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
2e030 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
2e040 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
2e050 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
2e060 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ence).)^.**.** ^
2e070 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
2e080 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
2e090 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
2e0a0 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
2e0b0 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
2e0c0 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
2e0d0 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
2e0e0 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
2e0f0 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
2e100 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
2e110 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64   ^Nor is the upd
2e120 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f  ate hook.** invo
2e130 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72  ked when rows ar
2e140 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  e deleted using 
2e150 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  the [truncate op
2e160 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  timization]..** 
2e170 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64  The exceptions d
2e180 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70  efined in this p
2e190 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63  aragraph might c
2e1a0 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
2e1b0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
2e1c0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
2e1d0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d  e update hook im
2e1e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2e1f0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
2e200 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
2e210 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
2e220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
2e230 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75  at invoked the u
2e240 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79  pdate hook.  Any
2e250 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
2e260 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2e270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2e280 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
2e290 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
2e2a0 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
2e2b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2e2c0 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
2e2d0 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64  riggered the upd
2e2e0 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74  ate hook..** Not
2e2f0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
2e300 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2e310 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
2e320 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
2e330 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
2e340 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
2e350 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
2e360 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
2e370 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
2e380 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
2e390 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50  pdate_hook(D,C,P
2e3a0 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  ) function.** re
2e3b0 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
2e3c0 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
2e3d0 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f  evious call.** o
2e3e0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
2e3f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e400 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
2e410 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
2e420 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65  l on D..**.** Se
2e430 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
2e440 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2e450 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2e460 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
2e470 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  .** interfaces..
2e480 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2e490 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
2e4a0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2e4b0 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
2e4c0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
2e4d0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
2e4e0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
2e4f0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
2e500 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
2e510 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
2e520 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b  Pager Cache.** K
2e530 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
2e540 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28   cache}.**.** ^(
2e550 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
2e560 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
2e570 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
2e580 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
2e590 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
2e5a0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
2e5b0 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
2e5c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
2e5d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
2e5e0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
2e5f0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
2e600 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
2e610 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
2e620 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
2e630 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
2e640 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a   is false.)^.**.
2e650 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e  ** ^Cache sharin
2e660 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
2e670 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
2e680 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
2e690 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
2e6a0 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
2e6b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
2e6c0 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
2e6d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
2e6e0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
2e6f0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2e700 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
2e710 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2e720 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73  ** ^(The cache s
2e730 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
2e740 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
2e750 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
2e760 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2e770 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
2e780 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2e790 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
2e7a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2e7b0 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
2e7c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e7d0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
2e7e0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
2e7f0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
2e800 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
2e810 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
2e820 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  pened.)^.**.** ^
2e830 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  (This routine re
2e840 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2e850 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
2e860 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
2e870 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
2e880 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
2e890 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2e8a0 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
2e8b0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72  e.)^.**.** ^Shar
2e8c0 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
2e8d0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
2e8e0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
2e8f0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
2e900 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2e910 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
2e920 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
2e930 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
2e940 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
2e950 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
2e960 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  icitly..**.** Se
2e970 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65  e Also:  [SQLite
2e980 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
2e990 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  de].*/.int sqlit
2e9a0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
2e9b0 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
2e9c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
2e9d0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
2e9e0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20  ap Memory.**.** 
2e9f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
2ea00 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
2ea10 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2ea20 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
2ea30 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
2ea40 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
2ea50 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
2ea60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2ea70 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
2ea80 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
2ea90 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73  ary.   Memory us
2eaa0 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
2eab0 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
2eac0 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
2ead0 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
2eae0 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
2eaf0 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ial memory..** ^
2eb00 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2eb10 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
2eb20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2eb30 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
2eb40 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
2eb50 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
2eb60 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
2eb70 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
2eb80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2eb90 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
2eba0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ebb0 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  EF: Impose A Lim
2ebc0 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
2ebd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ebe0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
2ebf0 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70  it() interface p
2ec00 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
2ec10 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61  imit.** on the a
2ec20 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
2ec30 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
2ec40 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
2ec50 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20  Lite..** ^If an 
2ec60 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74  internal allocat
2ec70 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2ec80 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
2ec90 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68  ed the.** soft h
2eca0 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  eap limit, [sqli
2ecb0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2ecc0 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  ry()] is invoked
2ecd0 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   one or.** more 
2ece0 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
2ecf0 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
2ed00 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
2ed10 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
2ed20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74  **.** ^The limit
2ed30 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74   is called "soft
2ed40 22 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71  " because if [sq
2ed50 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2ed60 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f  mory()].** canno
2ed70 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e  t free sufficien
2ed80 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76  t memory to prev
2ed90 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72  ent the limit fr
2eda0 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65  om being exceede
2edb0 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  d,.** the memory
2edc0 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e   is allocated an
2edd0 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72  yway and the cur
2ede0 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70  rent operation p
2edf0 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e  roceeds..**.** ^
2ee00 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65  A negative or ze
2ee10 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d  ro value for N m
2ee20 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20  eans that there 
2ee30 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20  is no soft heap 
2ee40 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71  limit and.** [sq
2ee50 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2ee60 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c  mory()] will onl
2ee70 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2ee80 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75   memory is exhau
2ee90 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  sted..** ^The de
2eea0 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
2eeb0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2eec0 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  mit is zero..**.
2eed0 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65  ** ^(SQLite make
2eee0 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20  s a best effort 
2eef0 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66  to honor the sof
2ef00 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a  t heap limit..**
2ef10 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74   But if the soft
2ef20 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e   heap limit cann
2ef30 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65  ot be honored, e
2ef40 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  xecution will.**
2ef50 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75   continue withou
2ef60 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66  t error or notif
2ef70 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73  ication.)^  This
2ef80 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69   is why the limi
2ef90 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61  t is.** called a
2efa0 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20   "soft" limit.  
2efb0 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  It is advisory o
2efc0 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  nly..**.** Prior
2efd0 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
2efe0 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72  on 3.5.0, this r
2eff0 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73  outine only cons
2f000 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f  trained the memo
2f010 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20  ry.** allocated 
2f020 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
2f030 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68  ad - the same th
2f040 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68  read in which th
2f050 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75  is routine.** ru
2f060 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77  ns.  Beginning w
2f070 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69  ith SQLite versi
2f080 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f  on 3.5.0, the so
2f090 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
2f0a0 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61  .** applied to a
2f0b0 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20  ll threads. The 
2f0c0 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20  value specified 
2f0d0 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61  for the soft hea
2f0e0 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e  p limit.** is an
2f0f0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20   upper bound on 
2f100 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79  the total memory
2f110 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
2f120 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a  all threads. In.
2f130 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  ** version 3.5.0
2f140 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63   there is no mec
2f150 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74  hanism for limit
2f160 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61  ing the heap usa
2f170 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69  ge for.** indivi
2f180 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f  dual threads..*/
2f190 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f  .void sqlite3_so
2f1a0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e  ft_heap_limit(in
2f1b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f1c0 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74  REF: Extract Met
2f1d0 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f  adata About A Co
2f1e0 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a  lumn Of A Table.
2f1f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
2f200 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61  ine returns meta
2f210 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65  data about a spe
2f220 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20  cific column of 
2f230 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61  a specific.** da
2f240 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63  tabase table acc
2f250 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68  essible using th
2f260 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f270 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
2f280 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
2f290 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61  first function a
2f2a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2f2b0 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64  The column is id
2f2c0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
2f2d0 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e  second, third an
2f2e0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2f2f0 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66  ers to.** this f
2f300 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65  unction. ^The se
2f310 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2f320 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d  s either the nam
2f330 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2f340 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e  e.** (i.e. "main
2f350 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e  ", "temp", or an
2f360 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2f370 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  se) containing t
2f380 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  he specified.** 
2f390 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e  table or NULL. ^
2f3a0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
2f3b0 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
2f3c0 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
2f3d0 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
2f3e0 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
2f3f0 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
2f400 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61  m used by the da
2f410 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f  tabase engine to
2f420 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75  .** resolve unqu
2f430 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65  alified table re
2f440 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  ferences..**.** 
2f450 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
2f460 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
2f470 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2f480 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20  n are the table 
2f490 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61  and column.** na
2f4a0 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65  me of the desire
2f4b0 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63  d column, respec
2f4c0 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20  tively. Neither 
2f4d0 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74  of these paramet
2f4e0 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  ers.** may be NU
2f4f0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64  LL..**.** ^Metad
2f500 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20  ata is returned 
2f510 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  by writing to th
2f520 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f  e memory locatio
2f530 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ns passed as the
2f540 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73   5th.** and subs
2f550 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72  equent parameter
2f560 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
2f570 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73  on. ^Any of thes
2f580 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20  e arguments may 
2f590 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77  be.** NULL, in w
2f5a0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f  hich case the co
2f5b0 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d  rresponding elem
2f5c0 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20  ent of metadata 
2f5d0 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a  is omitted..**.*
2f5e0 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  * ^(<blockquote>
2f5f0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2f600 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2f610 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68  h> Parameter <th
2f620 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65  > Output<br>Type
2f630 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69   <th>  Descripti
2f640 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
2f650 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74  > 5th <td> const
2f660 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61   char* <td> Data
2f670 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64   type.** <tr><td
2f680 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74  > 6th <td> const
2f690 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65   char* <td> Name
2f6a0 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c   of default coll
2f6b0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a  ation sequence.*
2f6c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c  * <tr><td> 7th <
2f6d0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2f6e0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2f6f0 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55  umn has a NOT NU
2f700 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  LL constraint.**
2f710 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74   <tr><td> 8th <t
2f720 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
2f730 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
2f740 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  mn is part of th
2f750 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a  e PRIMARY KEY.**
2f760 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74   <tr><td> 9th <t
2f770 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
2f780 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
2f790 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45  mn is [AUTOINCRE
2f7a0 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65  MENT].** </table
2f7b0 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
2f7c0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
2f7d0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74  memory pointed t
2f7e0 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74  o by the charact
2f7f0 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  er pointers retu
2f800 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  rned for the.** 
2f810 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65  declaration type
2f820 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   and collation s
2f830 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64  equence is valid
2f840 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20   only until the 
2f850 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  next.** call to 
2f860 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66  any SQLite API f
2f870 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
2f880 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2f890 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c   table is actual
2f8a0 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65  ly a view, an [e
2f8b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2f8c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  turned..**.** ^I
2f8d0 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
2f8e0 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64  column is "rowid
2f8f0 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f  ", "oid" or "_ro
2f900 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20  wid_" and an.** 
2f910 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2f920 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73   KEY] column has
2f930 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79   been explicitly
2f940 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20   declared, then 
2f950 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2f960 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2f970 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69   for the explici
2f980 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
2f990 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20  umn. ^(If there 
2f9a0 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69  is no.** explici
2f9b0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e  tly declared [IN
2f9c0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
2f9d0 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20  Y] column, then 
2f9e0 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61  the output.** pa
2f9f0 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74  rameters are set
2fa00 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
2fa10 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
2fa20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45  data type: "INTE
2fa30 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c  GER".**     coll
2fa40 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20  ation sequence: 
2fa50 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20  "BINARY".**     
2fa60 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20  not null: 0.**  
2fa70 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20     primary key: 
2fa80 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e  1.**     auto in
2fa90 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f  crement: 0.** </
2faa0 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  pre>)^.**.** ^(T
2fab0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
2fac0 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72   load one or mor
2fad0 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64  e schemas from d
2fae0 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49  atabase files. I
2faf0 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63  f an.** error oc
2fb00 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73  curs during this
2fb10 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
2fb20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61  the requested ta
2fb30 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  ble or column.**
2fb40 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64   cannot be found
2fb50 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
2fb60 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
2fb70 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
2fb80 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68  ge left.** in th
2fb90 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2fba0 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72  ection] (to be r
2fbb0 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73  etrieved using s
2fbc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29  qlite3_errmsg())
2fbd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  .)^.**.** ^This 
2fbe0 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  API is only avai
2fbf0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2fc00 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2fc10 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2fc20 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2fc30 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2fc40 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2fc50 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  bol defined..*/.
2fc60 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c  int sqlite3_tabl
2fc70 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74  e_column_metadat
2fc80 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  a(.  sqlite3 *db
2fc90 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2fca0 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68   /* Connection h
2fcb0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2fcc0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
2fcd0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2fce0 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20  se name or NULL 
2fcf0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2fd00 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20  *zTableName,    
2fd10 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a   /* Table name *
2fd20 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2fd30 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20  zColumnName,    
2fd40 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a  /* Column name *
2fd50 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2fd60 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20  *pzDataType,    
2fd70 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61  /* OUTPUT: Decla
2fd80 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f  red data type */
2fd90 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
2fda0 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f  pzCollSeq,     /
2fdb0 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74  * OUTPUT: Collat
2fdc0 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ion sequence nam
2fdd0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74  e */.  int *pNot
2fde0 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20  Null,           
2fdf0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2fe00 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63  ue if NOT NULL c
2fe10 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73  onstraint exists
2fe20 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d   */.  int *pPrim
2fe30 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20  aryKey,         
2fe40 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
2fe50 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74  e if column part
2fe60 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20   of PK */.  int 
2fe70 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20  *pAutoinc       
2fe80 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55          /* OUTPU
2fe90 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  T: True if colum
2fea0 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d  n is auto-increm
2feb0 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ent */.);../*.**
2fec0 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20   CAPI3REF: Load 
2fed0 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a  An Extension.**.
2fee0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
2fef0 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69  ce loads an SQLi
2ff00 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
2ff10 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61  rary from the na
2ff20 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  med file..**.** 
2ff30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61  ^The sqlite3_loa
2ff40 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
2ff50 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2ff60 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53   to load an.** S
2ff70 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
2ff80 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65  library containe
2ff90 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46  d in the file zF
2ffa0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ile..**.** ^The 
2ffb0 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a  entry point is z
2ffc0 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20  Proc..** ^zProc 
2ffd0 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69  may be 0, in whi
2ffe0 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65  ch case the name
2fff0 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f   of the entry po
30000 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20  int.** defaults 
30010 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65  to "sqlite3_exte
30020 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20  nsion_init"..** 
30030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61  ^The sqlite3_loa
30040 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e  d_extension() in
30050 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
30060 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ** [SQLITE_OK] o
30070 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53  n success and [S
30080 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
30090 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77  something goes w
300a0 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20  rong..** ^If an 
300b0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64  error occurs and
300c0 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74   pzErrMsg is not
300d0 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20   0, then the.** 
300e0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
300f0 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
30100 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d  face shall attem
30110 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70  pt to.** fill *p
30120 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72  zErrMsg with err
30130 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
30140 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79  stored in memory
30150 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
30160 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
30170 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e  c()]. The callin
30180 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68  g function.** sh
30190 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
301a0 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67  emory by calling
301b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
301c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73  ]..**.** ^Extens
301d0 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74  ion loading must
301e0 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   be enabled usin
301f0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e  g.** [sqlite3_en
30200 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
30210 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20  ion()] prior to 
30220 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49  calling this API
30230 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ,.** otherwise a
30240 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  n error will be 
30250 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
30260 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f  See also the [lo
30270 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53  ad_extension() S
30280 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f  QL function]..*/
30290 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61  .int sqlite3_loa
302a0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
302b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
302c0 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
302d0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
302e0 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
302f0 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
30300 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
30310 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
30320 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
30330 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
30340 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
30350 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
30360 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
30370 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
30380 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
30390 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
303a0 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
303b0 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
303c0 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
303d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
303e0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
303f0 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
30400 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73  ing.**.** ^So as
30410 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63   not to open sec
30420 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f  urity holes in o
30430 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  lder application
30440 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e  s that are.** un
30450 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c  prepared to deal
30460 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20   with extension 
30470 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20  loading, and as 
30480 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62  a means of disab
30490 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f  ling.** extensio
304a0 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20  n loading while 
304b0 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d  evaluating user-
304c0 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65  entered SQL, the
304d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a   following API.*
304e0 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  * is provided to
304f0 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74   turn the [sqlit
30500 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
30510 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f  n()] mechanism o
30520 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a  n and off..**.**
30530 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64   ^Extension load
30540 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65  ing is off by de
30550 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65  fault. See ticke
30560 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c  t #1863..** ^Cal
30570 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e  l the sqlite3_en
30580 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
30590 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69  ion() routine wi
305a0 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74  th onoff==1.** t
305b0 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e  o turn extension
305c0 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20   loading on and 
305d0 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f  call it with ono
305e0 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a  ff==0 to turn.**
305f0 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61   it back off aga
30600 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  in..*/.int sqlit
30610 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65  e3_enable_load_e
30620 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33  xtension(sqlite3
30630 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29   *db, int onoff)
30640 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30650 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79  F: Automatically
30660 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69   Load An Extensi
30670 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ons.**.** ^This 
30680 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b  API can be invok
30690 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74  ed at program st
306a0 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74  artup in order t
306b0 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e  o register.** on
306c0 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63  e or more static
306d0 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65  ally linked exte
306e0 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  nsions that will
306f0 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a   be available.**
30700 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74   to all new [dat
30710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30720 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  s]..**.** ^(This
30730 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
30740 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
30750 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79   extension entry
30760 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20   point.** in an 
30770 61 72 72 61 79 20 74 68 61 74 20 69 73 20 6f 62  array that is ob
30780 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
30790 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
307a0 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   That memory.** 
307b0 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62  is deallocated b
307c0 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  y [sqlite3_reset
307d0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
307e0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  )].)^.**.** ^Thi
307f0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  s function regis
30800 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f  ters an extensio
30810 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68  n entry point th
30820 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  at is.** automat
30830 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77  ically invoked w
30840 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64  henever a new [d
30850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30860 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64  on].** is opened
30870 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
30880 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
30890 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
308a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
308b0 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c  _v2()]..** ^Dupl
308c0 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73  icate extensions
308d0 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f   are detected so
308e0 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f   calling this ro
308f0 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c  utine.** multipl
30900 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  e times with the
30910 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20   same extension 
30920 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20  is harmless..** 
30930 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e  ^Automatic exten
30940 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f  sions apply acro
30950 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a  ss all threads..
30960 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
30970 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
30980 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74  id (*xEntryPoint
30990 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a  )(void));../*.**
309a0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
309b0 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e   Automatic Exten
309c0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
309d0 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69  ** ^(This functi
309e0 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20  on disables all 
309f0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
30a00 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a  tered automatic.
30a10 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49  ** extensions. I
30a20 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  t undoes the eff
30a30 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72  ect of all prior
30a40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74  .** [sqlite3_aut
30a50 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63  o_extension()] c
30a60 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  alls.)^.**.** ^T
30a70 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  his function dis
30a80 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20  ables automatic 
30a90 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c  extensions in al
30aa0 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f  l threads..*/.vo
30ab0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  id sqlite3_reset
30ac0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
30ad0 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  void);../*.** Th
30ae0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
30af0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
30b00 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75   mechanism is cu
30b10 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72  rrently consider
30b20 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65  ed.** to be expe
30b30 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69  rimental.  The i
30b40 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63  nterface might c
30b50 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61  hange in incompa
30b60 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49  tible ways..** I
30b70 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62  f this is a prob
30b80 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20  lem for you, do 
30b90 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65  not use the inte
30ba0 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69  rface at this ti
30bb0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  me..**.** When t
30bc0 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
30bd0 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69   mechanism stabi
30be0 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64  lizes, we will d
30bf0 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e  eclare the.** in
30c00 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73  terface fixed, s
30c10 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69  upport it indefi
30c20 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f  nitely, and remo
30c30 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e  ve this comment.
30c40 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63  .*/../*.** Struc
30c50 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68  tures used by th
30c60 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
30c70 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70  interface.*/.typ
30c80 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
30c90 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33  te3_vtab sqlite3
30ca0 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73  _vtab;.typedef s
30cb0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
30cc0 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33  dex_info sqlite3
30cd0 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70  _index_info;.typ
30ce0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
30cf0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
30d00 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
30d10 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72  sor;.typedef str
30d20 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
30d30 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  le sqlite3_modul
30d40 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
30d50 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
30d60 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
30d70 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f  ORDS: sqlite3_mo
30d80 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61  dule {virtual ta
30d90 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a  ble module}.**.*
30da0 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65  * This structure
30db0 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c  , sometimes call
30dc0 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20  ed a a "virtual 
30dd0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a  table module", .
30de0 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ** defines the i
30df0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
30e00 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
30e10 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73  es].  .** This s
30e20 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74  tructure consist
30e30 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68  s mostly of meth
30e40 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
30e50 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72  le..**.** ^A vir
30e60 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
30e70 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20  e is created by 
30e80 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72  filling in a per
30e90 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61  sistent.** insta
30ea0 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
30eb0 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e  cture and passin
30ec0 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  g a pointer to t
30ed0 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  hat instance.** 
30ee0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
30ef0 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20  te_module()] or 
30f00 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30f10 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a  module_v2()]..**
30f20 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69   ^The registrati
30f30 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64  on remains valid
30f40 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70   until it is rep
30f50 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65  laced by a diffe
30f60 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f  rent.** module o
30f70 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74  r until the [dat
30f80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30f90 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63  ] closes.  The c
30fa0 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69  ontent.** of thi
30fb0 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74  s structure must
30fc0 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c   not change whil
30fd0 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72  e it is register
30fe0 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64  ed with.** any d
30ff0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31000 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  on..*/.struct sq
31010 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20  lite3_module {. 
31020 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
31030 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28   int (*xCreate)(
31040 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a  sqlite3*, void *
31050 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20  pAux,.          
31060 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63       int argc, c
31070 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74  onst char *const
31080 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20  *argv,.         
31090 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74        sqlite3_vt
310a0 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61  ab **ppVTab, cha
310b0 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  r**);.  int (*xC
310c0 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a  onnect)(sqlite3*
310d0 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20  , void *pAux,.  
310e0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
310f0 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61   argc, const cha
31100 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20  r *const*argv,. 
31110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
31120 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56  lite3_vtab **ppV
31130 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20  Tab, char**);.  
31140 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78  int (*xBestIndex
31150 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
31160 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69  pVTab, sqlite3_i
31170 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69  ndex_info*);.  i
31180 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74  nt (*xDisconnect
31190 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
311a0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
311b0 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65  xDestroy)(sqlite
311c0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
311d0 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
311e0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
311f0 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62  ab, sqlite3_vtab
31200 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73  _cursor **ppCurs
31210 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  or);.  int (*xCl
31220 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ose)(sqlite3_vta
31230 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
31240 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c  t (*xFilter)(sql
31250 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
31260 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63  *, int idxNum, c
31270 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74  onst char *idxSt
31280 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  r,.             
31290 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c     int argc, sql
312a0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67  ite3_value **arg
312b0 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78  v);.  int (*xNex
312c0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  t)(sqlite3_vtab_
312d0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
312e0 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f  (*xEof)(sqlite3_
312f0 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
31300 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28   int (*xColumn)(
31310 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
31320 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f  sor*, sqlite3_co
31330 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20  ntext*, int);.  
31340 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71  int (*xRowid)(sq
31350 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
31360 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
31370 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e  4 *pRowid);.  in
31380 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c  t (*xUpdate)(sql
31390 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74  ite3_vtab *, int
313a0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  , sqlite3_value 
313b0 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  **, sqlite3_int6
313c0 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42  4 *);.  int (*xB
313d0 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  egin)(sqlite3_vt
313e0 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
313f0 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
31400 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
31410 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74  .  int (*xCommit
31420 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
31430 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
31440 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74  xRollback)(sqlit
31450 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
31460 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75  .  int (*xFindFu
31470 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f  nction)(sqlite3_
31480 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74  vtab *pVtab, int
31490 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61   nArg, const cha
314a0 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20  r *zName,.      
314b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
314c0 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29   void (**pxFunc)
314d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
314e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
314f0 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20  lue**),.        
31500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
31510 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20  oid **ppArg);.  
31520 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
31530 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
31540 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ab, const char *
31550 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  zNew);.};../*.**
31560 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
31570 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e  al Table Indexin
31580 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  g Information.**
31590 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
315a0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a  e3_index_info.**
315b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
315c0 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63  index_info struc
315d0 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62  ture and its sub
315e0 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73  structures is us
315f0 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e  ed to.** pass in
31600 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61  formation into a
31610 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20 72  nd receive the r
31620 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78  eply from the [x
31630 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65  BestIndex].** me
31640 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75  thod of a [virtu
31650 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
31660 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e  .  The fields un
31670 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61  der **Inputs** a
31680 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73  re the.** inputs
31690 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61   to xBestIndex a
316a0 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79  nd are read-only
316b0 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e  .  xBestIndex in
316c0 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73  serts its.** res
316d0 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a  ults into the **
316e0 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73  Outputs** fields
316f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43  ..**.** ^(The aC
31700 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61  onstraint[] arra
31710 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45 20  y records WHERE 
31720 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
31730 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a  ts of the form:.
31740 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d  **.** <pre>colum
31750 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a  n OP expr</pre>.
31760 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20 69  **.** where OP i
31770 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d  s =, &lt;, &lt;=
31780 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d  , &gt;, or &gt;=
31790 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74 69  .)^  ^(The parti
317a0 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20 69  cular operator i
317b0 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20 61  s.** stored in a
317c0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e  Constraint[].op.
317d0 29 5e 20 20 5e 28 54 68 65 20 69 6e 64 65 78 20  )^  ^(The index 
317e0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
317f0 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43   stored in.** aC
31800 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
31810 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74  umn.)^  ^(aConst
31820 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
31830 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
31840 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
31850 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
31860 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
31870 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
31880 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
31890 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
318a0 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a  f it cannot.)^.*
318b0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69  *.** ^The optimi
318c0 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
318d0 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
318e0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
318f0 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
31900 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
31910 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20  simplifications 
31920 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  to the WHERE cla
31930 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70  use in an attemp
31940 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d  t to.** get as m
31950 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65  any WHERE clause
31960 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20   terms into the 
31970 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65  form shown above
31980 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   as possible..**
31990 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e   ^The aConstrain
319a0 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
319b0 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
319c0 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61  use terms that a
319d0 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74  re.** relevant t
319e0 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
319f0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
31a00 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
31a10 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e  .** ^Information
31a20 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
31a30 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
31a40 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
31a50 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72  []..** ^Each ter
31a60 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
31a70 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
31a80 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
31a90 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
31aa0 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65   [xBestIndex] me
31ab0 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61  thod must fill a
31ac0 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
31ad0 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69  ] with informati
31ae0 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74  on.** about what
31af0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70   parameters to p
31b00 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20  ass to xFilter. 
31b10 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30   ^If argvIndex>0
31b20 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
31b30 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
31b40 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
31b50 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
31b60 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
31b70 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
31b80 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
31b90 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49  ry in argv.  ^(I
31ba0 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
31bb0 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
31bc0 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
31bd0 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
31be0 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
31bf0 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
31c00 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
31c10 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
31c20 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
31c30 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ite.)^.**.** ^Th
31c40 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
31c50 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
31c60 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
31c70 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  ed into the.** [
31c80 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e  xFilter] method.
31c90 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72  .** ^[sqlite3_fr
31ca0 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  ee()] is used to
31cb0 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
31cc0 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e  and only if.** n
31cd0 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20  eedToFreeIdxPtr 
31ce0 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e  is true..**.** ^
31cf0 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
31d00 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
31d10 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c  utput from [xFil
31d20 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c  ter]/[xNext] wil
31d30 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
31d40 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
31d50 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
31d60 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
31d70 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
31d80 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
31d90 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
31da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d  **.** ^The estim
31db0 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
31dc0 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
31dd0 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
31de0 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
31df0 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
31e00 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
31e10 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
31e20 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
31e30 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
31e40 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
31e50 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
31e60 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
31e70 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
31e80 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
31e90 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
31ea0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
31eb0 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
31ec0 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
31ed0 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
31ee0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
31ef0 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
31f00 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
31f10 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
31f20 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
31f30 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
31f40 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31f50 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
31f60 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
31f70 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
31f80 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
31f90 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
31fa0 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
31fb0 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
31fc0 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
31fd0 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
31fe0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
31ff0 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
32000 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
32010 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
32020 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
32030 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
32040 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
32050 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
32060 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
32070 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
32080 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
32090 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
320a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
320b0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
320c0 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
320d0 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
320e0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
320f0 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
32100 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
32110 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
32120 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
32130 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
32140 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
32150 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
32160 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
32170 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
32180 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32190 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
321a0 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74  ause */.  /* Out
321b0 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
321c0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
321d0 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
321e0 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
321f0 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
32200 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
32210 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
32220 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
32230 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
32240 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
32250 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
32260 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
32270 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
32280 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
32290 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
322a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
322b0 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
322c0 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
322d0 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
322e0 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
322f0 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
32300 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
32310 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
32320 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
32330 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
32340 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
32350 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
32360 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
32370 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
32380 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
32390 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
323a0 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
323b0 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
323c0 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
323d0 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
323e0 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
323f0 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
32400 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  };.#define SQLIT
32410 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
32420 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69  NT_EQ    2.#defi
32430 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
32440 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20  CONSTRAINT_GT   
32450 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
32460 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
32470 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69  NT_LE    8.#defi
32480 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
32490 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20  CONSTRAINT_LT   
324a0 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
324b0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
324c0 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65  INT_GE    32.#de
324d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
324e0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54  X_CONSTRAINT_MAT
324f0 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  CH 64../*.** CAP
32500 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
32510 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  A Virtual Table 
32520 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  Implementation.*
32530 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
32540 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f  ines are used to
32550 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77 20   register a new 
32560 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
32570 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20  odule] name..** 
32580 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75  ^Module names mu
32590 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65 64  st be registered
325a0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74   before.** creat
325b0 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ing a new [virtu
325c0 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20  al table] using 
325d0 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 62  the module and b
325e0 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a  efore using a.**
325f0 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69   preexisting [vi
32600 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72  rtual table] for
32610 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
32620 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e  ** ^The module n
32630 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65  ame is registere
32640 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  d on the [databa
32650 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
32660 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
32670 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
32680 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f  er.  ^The name o
32690 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20  f the module is 
326a0 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a  given by the .**
326b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
326c0 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70  r.  ^The third p
326d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
326e0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  inter to.** the 
326f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
32700 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
32710 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20  able module].   
32720 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70  ^The fourth.** p
32730 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
32740 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20  rbitrary client 
32750 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61  data pointer tha
32760 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
32770 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ugh.** into the 
32780 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
32790 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
327a0 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c 20   of the virtual 
327b0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20  table module.** 
327c0 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75  when a new virtu
327d0 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20 62  al table is be b
327e0 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20  eing created or 
327f0 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a  reinitialized..*
32800 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32810 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
32820 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 68  v2() interface h
32830 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61 6d  as a fifth param
32840 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
32850 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
32860 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
32870 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20  he pClientData. 
32880 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a   ^SQLite will.**
32890 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
328a0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
328b0 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  (if it is not NU
328c0 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a  LL) when SQLite.
328d0 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  ** no longer nee
328e0 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  ds the pClientDa
328f0 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  ta pointer.  ^Th
32900 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
32910 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74  _module().** int
32920 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
32930 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  lent to sqlite3_
32940 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
32950 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a  () with a NULL.*
32960 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f  * destructor..*/
32970 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
32980 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
32990 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
329a0 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
329b0 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
329c0 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
329d0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
329e0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
329f0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
32a00 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
32a10 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
32a20 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
32a30 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
32a40 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
32a50 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20  *pClientData    
32a60 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
32a70 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
32a80 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
32a90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32aa0 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
32ab0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
32ac0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
32ad0 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
32ae0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
32af0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
32b00 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
32b10 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
32b20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
32b30 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
32b40 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
32b50 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
32b60 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
32b70 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20  d *pClientData, 
32b80 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
32b90 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
32ba0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
32bb0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
32bc0 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
32bd0 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
32be0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
32bf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32c00 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
32c10 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a  nstance Object.*
32c20 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
32c30 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45  te3_vtab.**.** E
32c40 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61  very [virtual ta
32c50 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c  ble module] impl
32c60 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
32c70 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66  a subclass.** of
32c80 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20   this object to 
32c90 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69  describe a parti
32ca0 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a  cular instance.*
32cb0 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  * of the [virtua
32cc0 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20  l table].  Each 
32cd0 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a  subclass will.**
32ce0 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20   be tailored to 
32cf0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
32d00 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ds of the module
32d10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
32d20 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20  .** The purpose 
32d30 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
32d40 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
32d50 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
32d60 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f  hat are.** commo
32d70 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  n to all module 
32d80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
32d90 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20  .**.** ^Virtual 
32da0 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63  tables methods c
32db0 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20  an set an error 
32dc0 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67  message by assig
32dd0 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67  ning a.** string
32de0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
32df0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
32e00 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  )] to zErrMsg.  
32e10 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
32e20 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
32e30 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
32e40 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
32e50 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
32e60 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70  te3_free()].** p
32e70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e  rior to assignin
32e80 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74  g a new string t
32e90 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74  o zErrMsg.  ^Aft
32ea0 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
32eb0 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76  sage.** is deliv
32ec0 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63  ered up to the c
32ed0 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  lient applicatio
32ee0 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  n, the string wi
32ef0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
32f00 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20  lly.** freed by 
32f10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61  sqlite3_free() a
32f20 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66  nd the zErrMsg f
32f30 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72  ield will be zer
32f40 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  oed..*/.struct s
32f50 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20  qlite3_vtab {.  
32f60 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
32f70 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20  dule *pModule;  
32f80 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f  /* The module fo
32f90 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74  r this virtual t
32fa0 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52  able */.  int nR
32fb0 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ef;             
32fc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20            /* NO 
32fd0 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20  LONGER USED */. 
32fe0 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20   char *zErrMsg; 
32ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33000 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67   /* Error messag
33010 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  e from sqlite3_m
33020 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a  printf() */.  /*
33030 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
33040 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
33050 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
33060 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
33070 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
33080 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
33090 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20  al Table Cursor 
330a0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
330b0 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62  DS: sqlite3_vtab
330c0 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c  _cursor {virtual
330d0 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a   table cursor}.*
330e0 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
330f0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
33100 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
33110 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
33120 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f   of the.** follo
33130 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74  wing structure t
33140 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f  o describe curso
33150 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e  rs that point in
33160 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75  to the.** [virtu
33170 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72  al table] and ar
33180 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f  e used.** to loo
33190 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69  p through the vi
331a0 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75  rtual table.  Cu
331b0 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65  rsors are create
331c0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
331d0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78  sqlite3_module.x
331e0 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65  Open | xOpen] me
331f0 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75  thod of the modu
33200 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72  le and are destr
33210 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  oyed.** by the [
33220 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78  sqlite3_module.x
33230 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20  Close | xClose] 
33240 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73  method.  Cursors
33250 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20   are used.** by 
33260 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b  the [xFilter], [
33270 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20  xNext], [xEof], 
33280 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b  [xColumn], and [
33290 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a  xRowid] methods.
332a0 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ** of the module
332b0 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69  .  Each module i
332c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
332d0 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  ll define.** the
332e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75   content of a cu
332f0 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74  rsor structure t
33300 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e  o suit its own n
33310 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eeds..**.** This
33320 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73   superclass exis
33330 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64  ts in order to d
33340 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20  efine fields of 
33350 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a  the cursor that.
33360 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f  ** are common to
33370 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74   all implementat
33380 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  ions..*/.struct 
33390 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
333a0 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f  sor {.  sqlite3_
333b0 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20  vtab *pVtab;    
333c0 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
333d0 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f  le of this curso
333e0 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  r */.  /* Virtua
333f0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
33400 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
33410 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
33420 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
33430 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
33440 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20  EF: Declare The 
33450 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74  Schema Of A Virt
33460 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  ual Table.**.** 
33470 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61  ^The [xCreate] a
33480 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65  nd [xConnect] me
33490 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76  thods of a.** [v
334a0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
334b0 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69  ule] call this i
334c0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64  nterface.** to d
334d0 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61  eclare the forma
334e0 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64  t (the names and
334f0 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68   datatypes of th
33500 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a  e columns) of.**
33510 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
33520 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65  les they impleme
33530 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  nt..*/.int sqlit
33540 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
33550 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
33560 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a  char *zSQL);../*
33570 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76  .** CAPI3REF: Ov
33580 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f  erload A Functio
33590 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20  n For A Virtual 
335a0 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69  Table.**.** ^(Vi
335b0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
335c0 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61   provide alterna
335d0 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tive implementat
335e0 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e  ions of function
335f0 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b  s.** using the [
33600 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d  xFindFunction] m
33610 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69  ethod of the [vi
33620 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
33630 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c  le].  .** But gl
33640 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66  obal versions of
33650 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73   those functions
33660 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69  .** must exist i
33670 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76  n order to be ov
33680 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a  erloaded.)^.**.*
33690 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b  * ^(This API mak
336a0 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
336b0 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
336c0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
336d0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
336e0 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
336f0 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
33700 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
33710 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
33720 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
33730 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
33740 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
33750 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69  eated.)^  ^The i
33760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
33770 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63   of the new func
33780 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73  tion always caus
33790 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  es an exception 
337a0 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53  to be thrown.  S
337b0 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e  o.** the new fun
337c0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f  ction is not goo
337d0 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62  d for anything b
337e0 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f  y itself.  Its o
337f0 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69  nly.** purpose i
33800 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68  s to be a placeh
33810 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74  older function t
33820 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c  hat can be overl
33830 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76  oaded.** by a [v
33840 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a  irtual table]..*
33850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76  /.int sqlite3_ov
33860 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28  erload_function(
33870 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
33880 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c  char *zFuncName,
33890 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a   int nArg);../*.
338a0 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  ** The interface
338b0 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d   to the virtual-
338c0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
338d0 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62  defined above (b
338e0 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63  ack up.** to a c
338f0 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c  omment remarkabl
33900 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69  y similar to thi
33910 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e  s one) is curren
33920 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
33930 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
33940 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
33950 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
33960 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
33970 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
33980 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
33990 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
339a0 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
339b0 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
339c0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
339d0 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
339e0 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
339f0 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
33a00 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
33a10 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
33a20 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
33a30 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
33a40 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
33a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33a60 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20   A Handle To An 
33a70 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59  Open BLOB.** KEY
33a80 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e  WORDS: {BLOB han
33a90 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  dle} {BLOB handl
33aa0 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  es}.**.** An ins
33ab0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
33ac0 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
33ad0 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20  an open BLOB on 
33ae0 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
33af0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
33b00 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
33b10 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f  /O] can be perfo
33b20 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74  rmed..** ^Object
33b30 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61  s of this type a
33b40 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73  re created by [s
33b50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
33b60 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72  ()].** and destr
33b70 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
33b80 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
33b90 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
33ba0 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e  _blob_read()] an
33bb0 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  d [sqlite3_blob_
33bc0 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61  write()] interfa
33bd0 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ces.** can be us
33be0 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ed to read or wr
33bf0 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63  ite small subsec
33c00 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f  tions of the BLO
33c10 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  B..** ^The [sqli
33c20 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
33c30 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
33c40 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
33c50 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65  the BLOB in byte
33c60 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
33c70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ruct sqlite3_blo
33c80 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a  b sqlite3_blob;.
33c90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33ca0 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72   Open A BLOB For
33cb0 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f   Incremental I/O
33cc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
33cd0 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61  terfaces opens a
33ce0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20   [BLOB handle | 
33cf0 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42  handle] to the B
33d00 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69  LOB located.** i
33d10 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75  n row iRow, colu
33d20 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c  mn zColumn, tabl
33d30 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61  e zTable in data
33d40 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20  base zDb;.** in 
33d50 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
33d60 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20   same BLOB that 
33d70 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65  would be selecte
33d80 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  d by:.**.** <pre
33d90 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20  >.**     SELECT 
33da0 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62  zColumn FROM zDb
33db0 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72  .zTable WHERE [r
33dc0 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a  owid] = iRow;.**
33dd0 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
33de0 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61  ^If the flags pa
33df0 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a  rameter is non-z
33e00 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c  ero, then the BL
33e10 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
33e20 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69   read.** and wri
33e30 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69  te access. ^If i
33e40 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42  t is zero, the B
33e50 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
33e60 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a  r read access..*
33e70 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73  * ^It is not pos
33e80 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20  sible to open a 
33e90 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70  column that is p
33ea0 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20  art of an index 
33eb0 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b  or primary .** k
33ec0 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20  ey for writing. 
33ed0 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  ^If [foreign key
33ee0 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72   constraints] ar
33ef0 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73  e enabled, it is
33f00 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c   .** not possibl
33f10 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75  e to open a colu
33f20 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20  mn that is part 
33f30 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d  of a [child key]
33f40 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a   for writing..**
33f50 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
33f60 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
33f70 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65   is not the file
33f80 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69  name that contai
33f90 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  ns.** the databa
33fa0 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68  se but rather th
33fb0 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20  e symbolic name 
33fc0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
33fd0 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20  that.** appears 
33fe0 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79  after the AS key
33ff0 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64 61  word when the da
34000 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63  tabase is connec
34010 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43  ted using [ATTAC
34020 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  H]..** ^For the 
34030 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
34040 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  le, the database
34050 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e   name is "main".
34060 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61  .** ^For TEMP ta
34070 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61  bles, the databa
34080 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70  se name is "temp
34090 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75  "..**.** ^(On su
340a0 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f  ccess, [SQLITE_O
340b0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  K] is returned a
340c0 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42  nd the new [BLOB
340d0 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74   handle] is writ
340e0 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f  ten.** to *ppBlo
340f0 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  b. Otherwise an 
34100 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
34110 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70  returned and *pp
34120 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74  Blob is set.** t
34130 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e  o be a null poin
34140 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20  ter.)^.** ^This 
34150 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68  function sets th
34160 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
34170 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f  ection] error co
34180 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a  de and message.*
34190 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61  * accessible via
341a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
341b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
341c0 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20  3_errmsg()] and 
341d0 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74  related.** funct
341e0 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74  ions. ^Note that
341f0 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72   the *ppBlob var
34200 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20  iable is always 
34210 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61  initialized in a
34220 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b  .** way that mak
34230 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e  es it safe to in
34240 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c  voke [sqlite3_bl
34250 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a  ob_close()] on *
34260 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64  ppBlob.** regard
34270 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
34280 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  ess or failure o
34290 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a  f this routine..
342a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72  **.** ^(If the r
342b0 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68  ow that a BLOB h
342c0 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  andle points to 
342d0 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61  is modified by a
342e0 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b  n.** [UPDATE], [
342f0 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b  DELETE], or by [
34300 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64  ON CONFLICT] sid
34310 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65  e-effects.** the
34320 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  n the BLOB handl
34330 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22  e is marked as "
34340 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69  expired"..** Thi
34350 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79  s is true if any
34360 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
34370 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65  ow is changed, e
34380 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  ven a column.** 
34390 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f  other than the o
343a0 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ne the BLOB hand
343b0 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e  le is open on.)^
343c0 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73  .** ^Calls to [s
343d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
343e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
343f0 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66  _blob_write()] f
34400 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20  or.** a expired 
34410 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c  BLOB handle fail
34420 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20   with an return 
34430 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
34440 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61  ABORT]..** ^(Cha
34450 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74  nges written int
34460 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74  o a BLOB prior t
34470 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72  o the BLOB expir
34480 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  ing are not.** r
34490 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68  olled back by th
344a0 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20  e expiration of 
344b0 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20  the BLOB.  Such 
344c0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65  changes will eve
344d0 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69  ntually.** commi
344e0 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63  t if the transac
344f0 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74  tion continues t
34500 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a  o completion.)^.
34510 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b  **.** ^Use the [
34520 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
34530 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
34540 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
34550 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20   size of.** the 
34560 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54  opened blob.  ^T
34570 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
34580 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61  b may not be cha
34590 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  nged by this.** 
345a0 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 20  interface.  Use 
345b0 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c  the [UPDATE] SQL
345c0 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e   command to chan
345d0 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  ge the size of a
345e0 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20  .** blob..**.** 
345f0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69  ^The [sqlite3_bi
34600 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61  nd_zeroblob()] a
34610 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
34620 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69  lt_zeroblob()] i
34630 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64  nterfaces.** and
34640 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a   the built-in [z
34650 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e  eroblob] SQL fun
34660 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ction can be use
34670 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a  d, if desired,.*
34680 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65  * to create an e
34690 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65  mpty, zero-fille
346a0 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20  d blob in which 
346b0 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  to read or write
346c0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69   using.** this i
346d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
346e0 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75  To avoid a resou
346f0 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20  rce leak, every 
34700 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
34710 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75  e] should eventu
34720 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61  ally.** be relea
34730 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  sed by a call to
34740 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
34750 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  lose()]..*/.int 
34760 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
34770 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  n(.  sqlite3*,. 
34780 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
34790 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
347a0 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20  zTable,.  const 
347b0 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20  char *zColumn,. 
347c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
347d0 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73  Row,.  int flags
347e0 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ,.  sqlite3_blob
347f0 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a   **ppBlob.);../*
34800 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c  .** CAPI3REF: Cl
34810 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64 6c  ose A BLOB Handl
34820 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73 20  e.**.** ^Closes 
34830 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  an open [BLOB ha
34840 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 6c  ndle]..**.** ^Cl
34850 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68 61  osing a BLOB sha
34860 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75 72  ll cause the cur
34870 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
34880 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66   to commit.** if
34890 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f 74   there are no ot
348a0 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70 65  her BLOBs, no pe
348b0 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20 73  nding prepared s
348c0 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20 74  tatements, and t
348d0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
348e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e 20  onnection is in 
348f0 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  [autocommit mode
34900 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77 72  ]..** ^If any wr
34910 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20 74  ites were made t
34920 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65 79  o the BLOB, they
34930 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20 69   might be held i
34940 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69 6c  n cache.** until
34950 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72 61   the close opera
34960 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69 6c  tion if they wil
34970 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 43  l fit..**.** ^(C
34980 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42 20  losing the BLOB 
34990 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68 65  often forces the
349a0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74 20   changes.** out 
349b0 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20 69  to disk and so i
349c0 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72 73  f any I/O errors
349d0 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69 6c   occur, they wil
349e0 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a 2a  l likely occur.*
349f0 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68  * at the time wh
34a00 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 63  en the BLOB is c
34a10 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72 6f  losed.  Any erro
34a20 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64 75  rs that occur du
34a30 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67 20  ring.** closing 
34a40 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73 20  are reported as 
34a50 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72  a non-zero retur
34a60 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  n value.)^.**.**
34a70 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20 63   ^(The BLOB is c
34a80 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f  losed unconditio
34a90 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66 20  nally.  Even if 
34aa0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
34ab0 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  urns.** an error
34ac0 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42 20   code, the BLOB 
34ad0 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e  is still closed.
34ae0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  )^.**.** ^Callin
34af0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
34b00 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74  ith a null point
34b10 65 72 20 28 73 75 63 68 20 61 73 20 77 6f 75 6c  er (such as woul
34b20 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  d be returned.**
34b30 20 62 79 20 61 20 66 61 69 6c 65 64 20 63 61 6c   by a failed cal
34b40 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34b50 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20 61  ob_open()]) is a
34b60 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
34b70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34b80 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69 74  blob_close(sqlit
34b90 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a  e3_blob *);../*.
34ba0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
34bb0 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66 20  urn The Size Of 
34bc0 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 0a  An Open BLOB.**.
34bd0 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65 20  ** ^Returns the 
34be0 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f 66  size in bytes of
34bf0 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73 73   the BLOB access
34c00 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a 2a  ible via the .**
34c10 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 70   successfully op
34c20 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ened [BLOB handl
34c30 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20 61  e] in its only a
34c40 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a 2a  rgument.  ^The.*
34c50 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62 6c  * incremental bl
34c60 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73 20  ob I/O routines 
34c70 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f 72  can only read or
34c80 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78 69   overwriting exi
34c90 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63 6f  sting.** blob co
34ca0 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e 6e  ntent; they cann
34cb0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73 69  ot change the si
34cc0 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a 2a  ze of a blob..**
34cd0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34ce0 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
34cf0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
34d00 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
34d10 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
34d20 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
34d30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34d40 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
34d50 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
34d60 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
34d70 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
34d80 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
34d90 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
34da0 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
34db0 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
34dc0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
34dd0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
34de0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
34df0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34e00 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c 69  _blob_bytes(sqli
34e10 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
34e20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
34e30 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20 42  ad Data From A B
34e40 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c 6c  LOB Incrementall
34e50 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66  y.**.** ^(This f
34e60 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 20  unction is used 
34e70 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72 6f  to read data fro
34e80 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  m an open [BLOB 
34e90 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a 2a  handle] into a.*
34ea0 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69 65  * caller-supplie
34eb0 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74 65  d buffer. N byte
34ec0 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63 6f  s of data are co
34ed0 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65 72  pied into buffer
34ee0 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 6f   Z.** from the o
34ef0 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69  pen BLOB, starti
34f00 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
34f10 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  fset.)^.**.** ^I
34f20 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  f offset iOffset
34f30 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20   is less than N 
34f40 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
34f50 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a  nd of the BLOB,.
34f60 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
34f70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
34f80 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61  d no data is rea
34f90 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f 66  d.  ^If N or iOf
34fa0 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20  fset is.** less 
34fb0 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49  than zero, [SQLI
34fc0 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
34fd0 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
34fe0 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e 54  a is read..** ^T
34ff0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  he size of the b
35000 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74  lob (and hence t
35010 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65  he maximum value
35020 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a   of N+iOffset).*
35030 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
35040 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73  ned using the [s
35050 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
35060 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  s()] interface..
35070 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70  **.** ^An attemp
35080 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 61  t to read from a
35090 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20  n expired [BLOB 
350a0 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69  handle] fails wi
350b0 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63  th an.** error c
350c0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
350d0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  BORT]..**.** ^(O
350e0 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74  n success, sqlit
350f0 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20 72  e3_blob_read() r
35100 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
35110 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
35120 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
35130 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20  or an [extended 
35140 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
35150 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
35160 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   This routine on
35170 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42  ly works on a [B
35180 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63  LOB handle] whic
35190 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74  h has been creat
351a0 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72  ed.** by a prior
351b0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
351c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
351d0 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68  b_open()] and wh
351e0 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62  ich has not.** b
351f0 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73  een closed by [s
35200 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
35210 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61  e()].  Passing a
35220 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72  ny other pointer
35230 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72   in.** to this r
35240 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69  outine results i
35250 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  n undefined and 
35260 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
35270 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a  able behavior..*
35280 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
35290 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
352a0 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  te()]..*/.int sq
352b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
352c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
352d0 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20  void *Z, int N, 
352e0 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f  int iOffset);../
352f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57  *.** CAPI3REF: W
35300 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41  rite Data Into A
35310 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61   BLOB Incrementa
35320 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  lly.**.** ^This 
35330 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
35340 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69   to write data i
35350 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  nto an open [BLO
35360 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61  B handle] from a
35370 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c  .** caller-suppl
35380 69 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20 62  ied buffer. ^N b
35390 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
353a0 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65   copied from the
353b0 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74   buffer Z.** int
353c0 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c  o the open BLOB,
353d0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
353e0 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a  set iOffset..**.
353f0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f 42  ** ^If the [BLOB
35400 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20   handle] passed 
35410 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
35420 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70  ument was not op
35430 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74  ened for.** writ
35440 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20 70  ing (the flags p
35450 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
35460 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
35470 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20  ] was zero),.** 
35480 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
35490 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45  turns [SQLITE_RE
354a0 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ADONLY]..**.** ^
354b0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
354c0 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68  y only modify th
354d0 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68  e contents of th
354e0 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a  e BLOB; it is.**
354f0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
35500 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73 69   increase the si
35510 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73 69  ze of a BLOB usi
35520 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20  ng this API..** 
35530 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73  ^If offset iOffs
35540 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
35550 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  N bytes from the
35560 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42   end of the BLOB
35570 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
35580 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
35590 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
355a0 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20 69  ritten.  ^If N i
355b0 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a  s.** less than z
355c0 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ero [SQLITE_ERRO
355d0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
355e0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77 72  nd no data is wr
355f0 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 69  itten..** The si
35600 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 28  ze of the BLOB (
35610 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61  and hence the ma
35620 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e  ximum value of N
35630 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e  +iOffset).** can
35640 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
35650 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
35660 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
35670 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
35680 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20   ^An attempt to 
35690 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70 69  write to an expi
356a0 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  red [BLOB handle
356b0 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  ] fails with an.
356c0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66  ** error code of
356d0 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
356e0 20 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68 65    ^Writes to the
356f0 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75 72   BLOB that occur
35700 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  red.** before th
35710 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  e [BLOB handle] 
35720 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74 20  expired are not 
35730 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74  rolled back by t
35740 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f 6e  he.** expiration
35750 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c 20   of the handle, 
35760 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
35770 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 6d   those changes m
35780 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65 65  ight.** have bee
35790 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79  n overwritten by
357a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
357b0 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65 20  hat expired the 
357c0 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20 6f  BLOB handle.** o
357d0 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65 70  r by other indep
357e0 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  endent statement
357f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75  s..**.** ^(On su
35800 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62  ccess, sqlite3_b
35810 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74 75  lob_write() retu
35820 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a  rns SQLITE_OK..*
35830 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20  * Otherwise, an 
35840 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
35850 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72   an [extended er
35860 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
35870 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  urned.)^.**.** T
35880 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
35890 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
358a0 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
358b0 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
358c0 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
358d0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
358e0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
358f0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
35900 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
35910 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
35920 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
35930 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
35940 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
35950 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
35960 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
35970 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
35980 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
35990 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
359a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
359b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
359c0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
359d0 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71  e3_blob_write(sq
359e0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f  lite3_blob *, co
359f0 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74  nst void *z, int
35a00 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29   n, int iOffset)
35a10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35a20 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20  F: Virtual File 
35a30 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a 2a  System Objects.*
35a40 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 66  *.** A virtual f
35a50 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29 20  ilesystem (VFS) 
35a60 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  is an [sqlite3_v
35a70 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74 68  fs] object.** th
35a80 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  at SQLite uses t
35a90 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77 69  o interact.** wi
35aa0 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  th the underlyin
35ab0 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
35ac0 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74 65  em.  Most SQLite
35ad0 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69 74   builds come wit
35ae0 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64 65  h a.** single de
35af0 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20 69  fault VFS that i
35b00 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
35b10 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70 75  r the host compu
35b20 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53 65  ter..** New VFSe
35b30 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
35b40 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e 67  red and existing
35b50 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75 6e   VFSes can be un
35b60 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20 54  registered..** T
35b70 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74  he following int
35b80 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
35b90 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ided..**.** ^The
35ba0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e   sqlite3_vfs_fin
35bb0 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  d() interface re
35bc0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35bd0 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69  to a VFS given i
35be0 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61 6d  ts name..** ^Nam
35bf0 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e 73  es are case sens
35c00 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73  itive..** ^Names
35c10 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
35c20 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
35c30 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72 65  gs..** ^If there
35c40 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20   is no match, a 
35c50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
35c60 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
35c70 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55 4c   zVfsName is NUL
35c80 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  L then the defau
35c90 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72 6e  lt VFS is return
35ca0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20 56  ed..**.** ^New V
35cb0 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74 65  FSes are registe
35cc0 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65 33  red with sqlite3
35cd0 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e  _vfs_register().
35ce0 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56 46  .** ^Each new VF
35cf0 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64 65  S becomes the de
35d00 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68 65  fault VFS if the
35d10 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 69   makeDflt flag i
35d20 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  s set..** ^The s
35d30 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20 72  ame VFS can be r
35d40 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
35d50 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75 74  le times without
35d60 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f 20   injury..** ^To 
35d70 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67  make an existing
35d80 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65   VFS into the de
35d90 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73  fault VFS, regis
35da0 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20  ter it again.** 
35db0 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c  with the makeDfl
35dc0 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20  t flag set.  If 
35dd0 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46  two different VF
35de0 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  Ses with the.** 
35df0 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65  same name are re
35e00 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65  gistered, the be
35e10 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
35e20 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46  ned.  If a.** VF
35e30 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  S is registered 
35e40 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74  with a name that
35e50 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65   is NULL or an e
35e60 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20  mpty string,.** 
35e70 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
35e80 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
35e90 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74 65  **.** ^Unregiste
35ea0 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65  r a VFS with the
35eb0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72   sqlite3_vfs_unr
35ec0 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66  egister() interf
35ed0 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ace..** ^(If the
35ee0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
35ef0 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61 6e  unregistered, an
35f00 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68 6f  other VFS is cho
35f10 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64 65  sen as.** the de
35f20 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f 69  fault.  The choi
35f30 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20 56  ce for the new V
35f40 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  FS is arbitrary.
35f50 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66  )^.*/.sqlite3_vf
35f60 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  s *sqlite3_vfs_f
35f70 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ind(const char *
35f80 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73  zVfsName);.int s
35f90 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
35fa0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
35fb0 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b  , int makeDflt);
35fc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
35fd0 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69  _unregister(sqli
35fe0 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a  te3_vfs*);../*.*
35ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
36000 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  xes.**.** The SQ
36010 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
36020 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
36030 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e 63  r thread.** sync
36040 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68 6f  hronization. Tho
36050 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e 74  ugh they are int
36060 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72 6e  ended for intern
36070 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c  al.** use by SQL
36080 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20 6c  ite, code that l
36090 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51 4c  inks against SQL
360a0 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69 74  ite is.** permit
360b0 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20 6f  ted to use any o
360c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
360d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ..**.** The SQLi
360e0 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 63  te source code c
360f0 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c 65  ontains multiple
36100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
36110 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75 74  .** of these mut
36120 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41 6e  ex routines.  An
36130 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d 70   appropriate imp
36140 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
36150 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f 6d  s selected autom
36160 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d 70  atically at comp
36170 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68 65  ile-time.  ^(The
36180 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d   following.** im
36190 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72  plementations ar
361a0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  e available in t
361b0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a  he SQLite core:.
361c0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
361d0 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
361e0 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_OS2.** <li>   
361f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
36200 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  READ.** <li>   S
36210 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a  QLITE_MUTEX_W32.
36220 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
36230 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c  _MUTEX_NOOP.** <
36240 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  /ul>)^.**.** ^Th
36250 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e  e SQLITE_MUTEX_N
36260 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  OOP implementati
36270 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20 72  on is a set of r
36280 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20  outines.** that 
36290 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63  does no real loc
362a0 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70 72  king and is appr
362b0 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
362c0 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74  in.** a single-t
362d0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
362e0 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ion.  ^The SQLIT
362f0 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20  E_MUTEX_OS2,.** 
36300 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
36310 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54 45  READ, and SQLITE
36320 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c 65  _MUTEX_W32 imple
36330 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72  mentations.** ar
36340 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  e appropriate fo
36350 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20 55  r use on OS/2, U
36360 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77 73  nix, and Windows
36370 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
36380 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
36390 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
363a0 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72 65  MUTEX_APPDEF pre
363b0 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61 63  processor.** mac
363c0 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74 68  ro defined (with
363d0 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45 58   "-DSQLITE_MUTEX
363e0 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68 65  _APPDEF=1"), the
363f0 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  n no mutex.** im
36400 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
36410 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74 68  included with th
36420 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74 68  e library. In th
36430 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20 61  is case the.** a
36440 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
36450 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d 20  supply a custom 
36460 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
36470 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a 2a  tion using the.*
36480 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
36490 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20 6f  _MUTEX] option o
364a0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  f the sqlite3_co
364b0 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e 0a  nfig() function.
364c0 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e  ** before callin
364d0 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  g sqlite3_initia
364e0 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f 74  lize() or any ot
364f0 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69 74  her public sqlit
36500 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  e3_.** function 
36510 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69 74  that calls sqlit
36520 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
36530 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
36540 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
36550 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f  c() routine allo
36560 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d  cates a new.** m
36570 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73  utex and returns
36580 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
36590 2e 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e 73  . ^If it returns
365a0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65   NULL.** that me
365b0 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78  ans that a mutex
365c0 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c   could not be al
365d0 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69 74  located.  ^SQLit
365e0 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64  e.** will unwind
365f0 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72   its stack and r
36600 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20  eturn an error. 
36610 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 0a   ^(The argument.
36620 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  ** to sqlite3_mu
36630 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f  tex_alloc() is o
36640 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ne of these inte
36650 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  ger constants:.*
36660 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
36670 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
36680 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  FAST.** <li>  SQ
36690 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
366a0 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
366b0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
366c0 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e  C_MASTER.** <li>
366d0 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
366e0 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69  TATIC_MEM.** <li
366f0 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
36700 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c  STATIC_MEM2.** <
36710 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
36720 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a  X_STATIC_PRNG.**
36730 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
36740 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a  TEX_STATIC_LRU.*
36750 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
36760 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32  UTEX_STATIC_LRU2
36770 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
36780 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 77 6f  * ^The first two
36790 20 63 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c 49   constants (SQLI
367a0 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e  TE_MUTEX_FAST an
367b0 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  d SQLITE_MUTEX_R
367c0 45 43 55 52 53 49 56 45 29 0a 2a 2a 20 63 61 75  ECURSIVE).** cau
367d0 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  se sqlite3_mutex
367e0 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65 61  _alloc() to crea
367f0 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74 65  te.** a new mute
36800 78 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d 75 74  x.  ^The new mut
36810 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20  ex is recursive 
36820 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  when SQLITE_MUTE
36830 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69  X_RECURSIVE.** i
36840 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e  s used but not n
36850 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68  ecessarily so wh
36860 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
36870 46 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a 2a  FAST is used..**
36880 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65   The mutex imple
36890 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e  mentation does n
368a0 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20  ot need to make 
368b0 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  a distinction.**
368c0 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
368d0 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20  MUTEX_RECURSIVE 
368e0 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
368f0 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65 73  _FAST if it does
36900 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e  .** not want to.
36910 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f    ^SQLite will o
36920 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72 65  nly request a re
36930 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69 6e  cursive mutex in
36940 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65 20  .** cases where 
36950 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73 20  it really needs 
36960 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66 61 73 74  one.  ^If a fast
36970 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65  er non-recursive
36980 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
36990 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69  entation is avai
369a0 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73  lable on the hos
369b0 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20  t platform, the 
369c0 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a  mutex subsystem.
369d0 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  ** might return 
369e0 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20  such a mutex in 
369f0 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49  response to SQLI
36a00 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a  TE_MUTEX_FAST..*
36a10 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72 20  *.** ^The other 
36a20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65  allowed paramete
36a30 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75  rs to sqlite3_mu
36a40 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e 79  tex_alloc() (any
36a50 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20 74  thing other.** t
36a60 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  han SQLITE_MUTEX
36a70 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45  _FAST and SQLITE
36a80 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
36a90 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a 2a  ) each return.**
36aa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
36ab0 73 74 61 74 69 63 20 70 72 65 65 78 69 73 74 69  static preexisti
36ac0 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53 69 78 20  ng mutex.  ^Six 
36ad0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  static mutexes a
36ae0 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68  re.** used by th
36af0 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  e current versio
36b00 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75  n of SQLite.  Fu
36b10 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
36b20 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61   SQLite.** may a
36b30 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  dd additional st
36b40 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53  atic mutexes.  S
36b50 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72  tatic mutexes ar
36b60 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a  e for internal.*
36b70 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65 20  * use by SQLite 
36b80 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
36b90 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51 4c  ons that use SQL
36ba0 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ite mutexes shou
36bb0 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74  ld.** use only t
36bc0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
36bd0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  es returned by S
36be0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
36bf0 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55   or.** SQLITE_MU
36c00 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a  TEX_RECURSIVE..*
36c10 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
36c20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79  if one of the dy
36c30 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61  namic mutex para
36c40 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d  meters (SQLITE_M
36c50 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20  UTEX_FAST.** or 
36c60 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
36c70 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64 20  URSIVE) is used 
36c80 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74  then sqlite3_mut
36c90 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65  ex_alloc().** re
36ca0 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e  turns a differen
36cb0 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79  t mutex on every
36cc0 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f 72   call.  ^But for
36cd0 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d   the static.** m
36ce0 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65 20  utex types, the 
36cf0 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65  same mutex is re
36d00 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20  turned on every 
36d10 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a  call that has.**
36d20 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e   the same type n
36d30 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
36d40 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
36d50 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64  free() routine d
36d60 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65  eallocates a pre
36d70 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63  viously.** alloc
36d80 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74  ated dynamic mut
36d90 65 78 2e 20 20 5e 53 51 4c 69 74 65 20 69 73 20  ex.  ^SQLite is 
36da0 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c  careful to deall
36db0 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20 64  ocate every.** d
36dc0 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68 61  ynamic mutex tha
36dd0 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20  t it allocates. 
36de0 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   The dynamic mut
36df0 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62 65  exes must not be
36e00 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20   in.** use when 
36e10 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f 63  they are dealloc
36e20 61 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69 6e  ated.  Attemptin
36e30 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  g to deallocate 
36e40 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65  a static.** mute
36e50 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  x results in und
36e60 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
36e70 20 20 5e 53 51 4c 69 74 65 20 6e 65 76 65 72 20    ^SQLite never 
36e80 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20 61  deallocates.** a
36e90 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
36ea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36eb0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20  3_mutex_enter() 
36ec0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
36ed0 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65 73  x_try() routines
36ee0 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20 65   attempt.** to e
36ef0 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20 5e  nter a mutex.  ^
36f00 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
36f10 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74  d is already wit
36f20 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a  hin the mutex,.*
36f30 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
36f40 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f  enter() will blo
36f50 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  ck and sqlite3_m
36f60 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20  utex_try() will 
36f70 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
36f80 5f 42 55 53 59 2e 20 20 5e 54 68 65 20 73 71 6c  _BUSY.  ^The sql
36f90 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
36fa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36fb0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a  ns [SQLITE_OK].*
36fc0 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75  * upon successfu
36fd0 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74 65  l entry.  ^(Mute
36fe0 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  xes created usin
36ff0 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  g.** SQLITE_MUTE
37000 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20  X_RECURSIVE can 
37010 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69  be entered multi
37020 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65  ple times by the
37030 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a   same thread..**
37040 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74   In such cases t
37050 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73  he,.** mutex mus
37060 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65  t be exited an e
37070 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74  qual number of t
37080 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74  imes before anot
37090 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61  her thread.** ca
370a0 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49 66  n enter.)^  ^(If
370b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
370c0 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72 20   tries to enter 
370d0 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e  any other.** kin
370e0 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65 20  d of mutex more 
370f0 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62  than once, the b
37100 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
37110 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ined..** SQLite 
37120 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62  will never exhib
37130 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76  it.** such behav
37140 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75  ior in its own u
37150 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 29 5e  se of mutexes.)^
37160 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73 79  .**.** ^(Some sy
37170 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d 70  stems (for examp
37180 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29 20  le, Windows 95) 
37190 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 74  do not support t
371a0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
371b0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 73  implemented by s
371c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
371d0 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73 79  ().  On those sy
371e0 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f 6d  stems, sqlite3_m
371f0 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77 69  utex_try().** wi
37200 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
37210 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 54   SQLITE_BUSY.  T
37220 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f  he SQLite core o
37230 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a 2a  nly ever uses.**
37240 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
37250 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69 6d  ry() as an optim
37260 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73 20  ization so this 
37270 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62 65  is acceptable be
37280 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  havior.)^.**.** 
37290 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
372a0 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74 69  ex_leave() routi
372b0 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65 78  ne exits a mutex
372c0 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72 65   that was.** pre
372d0 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64 20  viously entered 
372e0 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  by the same thre
372f0 61 64 2e 20 20 20 5e 28 54 68 65 20 62 65 68 61  ad.   ^(The beha
37300 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66  vior.** is undef
37310 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65  ined if the mute
37320 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  x is not current
37330 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68  ly entered by th
37340 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72  e.** calling thr
37350 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75  ead or is not cu
37360 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65  rrently allocate
37370 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  d.  SQLite will.
37380 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68  ** never do eith
37390 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  er.)^.**.** ^If 
373a0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
373b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
373c0 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f 6d  ter(), sqlite3_m
373d0 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a 2a  utex_try(), or.*
373e0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
373f0 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55 4c  leave() is a NUL
37400 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
37410 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69 6e  all three routin
37420 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73 20  es.** behave as 
37430 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53 65  no-ops..**.** Se
37440 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
37450 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 61  _mutex_held()] a
37460 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  nd [sqlite3_mute
37470 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a 2f  x_notheld()]..*/
37480 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  .sqlite3_mutex *
37490 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
374a0 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 73  loc(int);.void s
374b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65  qlite3_mutex_fre
374c0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
374d0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
374e0 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c 69  mutex_enter(sqli
374f0 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
37500 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
37510 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ry(sqlite3_mutex
37520 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
37530 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71 6c  _mutex_leave(sql
37540 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f  ite3_mutex*);../
37550 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
37560 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62 6a  utex Methods Obj
37570 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
37580 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
37590 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73 20  ructure defines 
375a0 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f  the low-level ro
375b0 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74  utines.** used t
375c0 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75  o allocate and u
375d0 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a  se mutexes..**.*
375e0 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20 64  * Usually, the d
375f0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d 70  efault mutex imp
37600 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f  lementations pro
37610 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  vided by SQLite 
37620 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e  are.** sufficien
37630 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 75  t, however the u
37640 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74 69  ser has the opti
37650 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74 69  on of substituti
37660 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69  ng a custom.** i
37670 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
37680 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64 65  r specialized de
37690 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79 73  ployments or sys
376a0 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20 53  tems for which S
376b0 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
376c0 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69 74  t provide a suit
376d0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
376e0 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61 73  ion. In this cas
376f0 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20 63  e, the user.** c
37700 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75 6c  reates and popul
37710 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63 65  ates an instance
37720 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
37730 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f  re to pass.** to
37740 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
37750 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68 65  ) along with the
37760 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
37770 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a  MUTEX] option..*
37780 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20  * Additionally, 
37790 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
377a0 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63 61  his structure ca
377b0 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e 0a  n be used as an.
377c0 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61 62  ** output variab
377d0 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e 67  le when querying
377e0 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72 20   the system for 
377f0 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74 65  the current mute
37800 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  x.** implementat
37810 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20 5b  ion, using the [
37820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
37830 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  TMUTEX] option..
37840 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  **.** ^The xMute
37850 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65 66  xInit method def
37860 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
37870 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65  ucture is invoke
37880 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
37890 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69 7a  system initializ
378a0 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71 6c  ation by the sql
378b0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
378c0 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  ) function..** ^
378d0 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 72  The xMutexInit r
378e0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 20  outine is calle 
378f0 62 79 20 53 51 4c 69 74 65 20 65 78 61 63 74 6c  by SQLite exactl
37900 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 0a  y once for each.
37910 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  ** effective cal
37920 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e  l to [sqlite3_in
37930 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 0a  itialize()]..**.
37940 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e  ** ^The xMutexEn
37950 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64  d method defined
37960 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
37970 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  re is invoked as
37980 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74  .** part of syst
37990 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20 74  em shutdown by t
379a0 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
379b0 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e 20  own() function. 
379c0 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  The.** implement
379d0 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d 65  ation of this me
379e0 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 65 64  thod is expected
379f0 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c 20   to release all 
37a00 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20 72  outstanding.** r
37a10 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e 65  esources obtaine
37a20 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 20 6d  d by the mutex m
37a30 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e 74  ethods implement
37a40 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c 6c  ation, especiall
37a50 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61 69  y.** those obtai
37a60 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 74 65  ned by the xMute
37a70 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20 5e  xInit method.  ^
37a80 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 0a  The xMutexEnd().
37a90 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
37aa0 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20  invoked exactly 
37ab0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61  once for each ca
37ac0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
37ad0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a  hutdown()]..**.*
37ae0 2a 20 5e 28 54 68 65 20 72 65 6d 61 69 6e 69 6e  * ^(The remainin
37af0 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73 20  g seven methods 
37b00 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
37b10 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 74 65  structure (xMute
37b20 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65  xAlloc,.** xMute
37b30 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e 74  xFree, xMutexEnt
37b40 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20 78  er, xMutexTry, x
37b50 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75 74  MutexLeave, xMut
37b60 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d  exHeld and.** xM
37b70 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70  utexNotheld) imp
37b80 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f  lement the follo
37b90 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20  wing interfaces 
37ba0 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a 0a  (respectively):.
37bb0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
37bc0 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
37bd0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f  utex_alloc()] </
37be0 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
37bf0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
37c00 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ee()] </li>.**  
37c10 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37c20 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c  mutex_enter()] <
37c30 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
37c40 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74  [sqlite3_mutex_t
37c50 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ry()] </li>.**  
37c60 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37c70 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c  mutex_leave()] <
37c80 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
37c90 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68  [sqlite3_mutex_h
37ca0 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  eld()] </li>.** 
37cb0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
37cc0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
37cd0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ] </li>.** </ul>
37ce0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e 6c  )^.**.** The onl
37cf0 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  y difference is 
37d00 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 63 20  that the public 
37d10 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e 63  sqlite3_XXX func
37d20 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65 64  tions enumerated
37d30 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e 74  .** above silent
37d40 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69 6e  ly ignore any in
37d50 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20 70  vocations that p
37d60 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ass a NULL point
37d70 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
37d80 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68   a valid mutex h
37d90 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c 65  andle. The imple
37da0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
37db0 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65  e methods define
37dc0 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74 72  d.** by this str
37dd0 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20 72  ucture are not r
37de0 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64 6c  equired to handl
37df0 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65  e this case, the
37e00 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20 70   results.** of p
37e10 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
37e20 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66  inter instead of
37e30 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20 68   a valid mutex h
37e40 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66 69  andle are undefi
37e50 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74 20  ned.** (i.e. it 
37e60 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 74 6f  is acceptable to
37e70 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70 6c   provide an impl
37e80 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
37e90 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a 20  segfaults if.** 
37ea0 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20 4e  it is passed a N
37eb0 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a 2a  ULL pointer)..**
37ec0 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e  .** The xMutexIn
37ed0 69 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73 74  it() method must
37ee0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
37ef0 20 5e 49 74 20 6d 75 73 74 20 62 65 20 68 61 72   ^It must be har
37f00 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76 6f  mless to.** invo
37f10 6b 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20  ke xMutexInit() 
37f20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  mutiple times wi
37f30 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
37f40 6f 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f 75  ocess and withou
37f50 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e 67  t.** intervening
37f60 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65 78   calls to xMutex
37f70 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20 61  End().  Second a
37f80 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
37f90 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65 78  lls to.** xMutex
37fa0 49 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20 6e  Init() must be n
37fb0 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78 4d  o-ops..**.** ^xM
37fc0 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20  utexInit() must 
37fd0 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
37fe0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37ff0 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f   ([sqlite3_mallo
38000 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73 20  c()].** and its 
38010 61 73 73 6f 63 69 61 74 65 73 29 2e 20 20 5e 53  associates).  ^S
38020 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78  imilarly, xMutex
38030 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74  Alloc() must not
38040 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f   use SQLite memo
38050 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
38060 20 66 6f 72 20 61 20 73 74 61 74 69 63 20 6d 75   for a static mu
38070 74 65 78 2e 20 20 5e 48 6f 77 65 76 65 72 20 78  tex.  ^However x
38080 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 79  MutexAlloc() may
38090 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 6d   use SQLite.** m
380a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
380b0 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20 72   for a fast or r
380c0 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e 0a  ecursive mutex..
380d0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
380e0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d  ll invoke the xM
380f0 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64  utexEnd() method
38100 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   when [sqlite3_s
38110 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a  hutdown()] is.**
38120 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c   called, but onl
38130 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20 63  y if the prior c
38140 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69  all to xMutexIni
38150 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54  t returned SQLIT
38160 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74  E_OK..** If xMut
38170 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20  exInit fails in 
38180 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20 65  any way, it is e
38190 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e  xpected to clean
381a0 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c 66   up after itself
381b0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74  .** prior to ret
381c0 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64  urning..*/.typed
381d0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
381e0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20  3_mutex_methods 
381f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
38200 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
38210 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
38220 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d  ods {.  int (*xM
38230 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b  utexInit)(void);
38240 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45  .  int (*xMutexE
38250 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c  nd)(void);.  sql
38260 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d  ite3_mutex *(*xM
38270 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b  utexAlloc)(int);
38280 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78  .  void (*xMutex
38290 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75  Free)(sqlite3_mu
382a0 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
382b0 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71  *xMutexEnter)(sq
382c0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
382d0 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72    int (*xMutexTr
382e0 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  y)(sqlite3_mutex
382f0 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d   *);.  void (*xM
38300 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74  utexLeave)(sqlit
38310 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69  e3_mutex *);.  i
38320 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29  nt (*xMutexHeld)
38330 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
38340 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
38350 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65  xNotheld)(sqlite
38360 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a  3_mutex *);.};..
38370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38380 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74 69  Mutex Verificati
38390 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
383a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  * The sqlite3_mu
383b0 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20 73  tex_held() and s
383c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
383d0 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73 0a  held() routines.
383e0 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ** are intended 
383f0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
38400 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
38410 74 73 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65  ts.  ^The SQLite
38420 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75   core.** never u
38430 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
38440 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65  es except inside
38450 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64   an assert() and
38460 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
38470 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20   are advised to 
38480 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20  follow the lead 
38490 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 5e 54  of the core.  ^T
384a0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6f  he SQLite core o
384b0 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73 20  nly.** provides 
384c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
384d0 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
384e0 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  es when it is co
384f0 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 74  mpiled.** with t
38500 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  he SQLITE_DEBUG 
38510 66 6c 61 67 2e 20 20 5e 45 78 74 65 72 6e 61 6c  flag.  ^External
38520 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
38530 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f 6e  ations.** are on
38540 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20 70  ly required to p
38550 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f 75  rovide these rou
38560 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45 5f  tines if SQLITE_
38570 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66 69  DEBUG is.** defi
38580 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42 55  ned and if NDEBU
38590 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65 64  G is not defined
385a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
385b0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 72  outines should r
385c0 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
385d0 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69 72  e mutex in their
385e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73 20   argument.** is 
385f0 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c 64  held or not held
38600 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c 20  , respectively, 
38610 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  by the calling t
38620 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  hread..**.** ^Th
38630 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38640 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65 64   is not required
38650 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65 72   to provided ver
38660 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a 2a  sions of these.*
38670 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
38680 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20 49  actually work. I
38690 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  f the implementa
386a0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70 72  tion does not pr
386b0 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a 2a  ovide working.**
386c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65   versions of the
386d0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74 20  se routines, it 
386e0 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74 20  should at least 
386f0 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74 68  provide stubs th
38700 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65 74  at always.** ret
38710 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61 74  urn true so that
38720 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67 65   one does not ge
38730 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65 72  t spurious asser
38740 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a 2a  tion failures..*
38750 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67  *.** ^If the arg
38760 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
38770 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69 73  _mutex_held() is
38780 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
38790 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75 74  then.** the rout
387a0 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ine should retur
387b0 6e 20 31 2e 20 20 20 54 68 69 73 20 73 65 65 6d  n 1.   This seem
387c0 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74  s counter-intuit
387d0 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65  ive since.** cle
387e0 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63  arly the mutex c
387f0 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66  annot be held if
38800 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69   it does not exi
38810 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20  st.  But the.** 
38820 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d  the reason the m
38830 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78  utex does not ex
38840 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20 74  ist is because t
38850 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a  he build is not.
38860 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73  ** using mutexes
38870 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74  .  And we do not
38880 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72 74   want the assert
38890 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  () containing th
388a0 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  e.** call to sql
388b0 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28  ite3_mutex_held(
388c0 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20  ) to fail, so a 
388d0 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20  non-zero return 
388e0 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70  is.** the approp
388f0 72 69 61 74 65