/ Hex Artifact Content
Login

Artifact caf60df0991a14e22cce8243b9caa1c1dbd09d42:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
90c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
90d0: 71 6c 69 74 65 33 5f 73 68 6d 20 73 71 6c 69 74  qlite3_shm sqlit
90e0: 65 33 5f 73 68 6d 3b 0a 73 74 72 75 63 74 20 73  e3_shm;.struct s
90f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
9100: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
9110: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
9120: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
9130: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32  ber (currently 2
9140: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
9150: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
9160: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
9170: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
9180: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
9190: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
91a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
91b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
91c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
91d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
91e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
91f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
9200: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9210: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9220: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9230: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9240: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
9250: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
9260: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
9270: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
9280: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
9290: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
92a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
92b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
92c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
92d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
92e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
92f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
9300: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9310: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9320: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9330: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9340: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9350: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9360: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
9370: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
9380: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
9390: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
93a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
93b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
93c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
93d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
93e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
93f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
9400: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9410: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9420: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9430: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9440: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
9450: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
9460: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
9470: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
9480: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
9490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
94a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
94b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
94e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
94f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9500: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9520: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9530: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9540: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9550: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9560: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9570: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
9580: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9590: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
95a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
95b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
95c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
95d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
95e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
95f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
9600: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
9610: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
9620: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9630: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
9640: 68 6d 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  hm**);.  int (*x
9650: 53 68 6d 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ShmSize)(sqlite3
9660: 5f 73 68 6d 2a 2c 20 69 6e 74 20 72 65 71 53 69  _shm*, int reqSi
9670: 7a 65 2c 20 69 6e 74 20 2a 70 4e 65 77 53 69 7a  ze, int *pNewSiz
9680: 65 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  e, char**);.  in
9690: 74 20 28 2a 78 53 68 6d 52 65 6c 65 61 73 65 29  t (*xShmRelease)
96a0: 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b 0a  (sqlite3_shm*);.
96b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 50 75 73 68    int (*xShmPush
96c0: 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b  )(sqlite3_shm*);
96d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 50 75 6c  .  int (*xShmPul
96e0: 6c 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29  l)(sqlite3_shm*)
96f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
9700: 63 6b 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a  ck)(sqlite3_shm*
9710: 2c 20 69 6e 74 20 64 65 73 69 72 65 64 4c 6f 63  , int desiredLoc
9720: 6b 2c 20 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 2c  k, int *gotLock,
9730: 20 69 6e 74 20 73 68 6f 75 6c 64 42 6c 6f 63 6b   int shouldBlock
9740: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 43  );.  int (*xShmC
9750: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 73 68  lose)(sqlite3_sh
9760: 6d 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  m*);.  int (*xSh
9770: 6d 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  mDelete)(sqlite3
9780: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9790: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 69 6e 74  r *zName);.  int
97a0: 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
97b0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
97c0: 63 68 61 72 20 2a 7a 4f 6c 64 2c 20 63 6f 6e 73  char *zOld, cons
97d0: 74 20 63 68 61 72 20 2a 7a 4e 65 77 2c 20 69 6e  t char *zNew, in
97e0: 74 20 64 69 72 53 79 6e 63 29 3b 0a 20 20 69 6e  t dirSync);.  in
97f0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9800: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
9810: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
9820: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
9830: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
9840: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
9850: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
9860: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9870: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
9880: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
9890: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
98a0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
98b0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
98c0: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
98d0: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
98e0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
98f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9900: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
9910: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
9920: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
9930: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
9940: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
9950: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
9960: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
9970: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
9980: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
9990: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
99a0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
99b0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
99c0: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
99d0: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
99e0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
99f0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9a00: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
9a10: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
9a20: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
9a30: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
9a40: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
9a50: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9a60: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
9a70: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
9a80: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9a90: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
9aa0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
9ab0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9ac0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
9ad0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
9ae0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
9af0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
9b00: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
9b10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9b20: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
9b30: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9b40: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
9b50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
9b60: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
9b70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9b80: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
9b90: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
9ba0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
9bb0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
9bc0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
9bd0: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 73 74 61 74  ous locking stat
9be0: 65 73 20 74 68 61 74 0a 2a 2a 20 61 6e 20 73 71  es that.** an sq
9bf0: 6c 69 74 65 33 5f 73 68 6d 20 6f 62 6a 65 63 74  lite3_shm object
9c00: 20 63 61 6e 20 62 65 20 69 6e 2e 20 20 54 68 65   can be in.  The
9c10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 51 55 45 52   SQLITE_SHM_QUER
9c20: 59 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 73 20  Y integer.** is 
9c30: 6e 6f 74 20 61 20 76 61 6c 69 64 20 64 61 74 61  not a valid data
9c40: 20 2d 20 69 74 20 69 73 20 61 20 63 6f 6e 73 74   - it is a const
9c50: 61 6e 74 20 70 61 73 74 65 64 20 74 6f 20 74 68  ant pasted to th
9c60: 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 66  e .** sqlite3_vf
9c70: 73 2e 78 53 68 6d 4c 6f 63 6b 28 29 20 6d 65 74  s.xShmLock() met
9c80: 68 6f 64 20 66 6f 72 20 71 75 65 72 79 69 6e 67  hod for querying
9c90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 6f 63   the current loc
9ca0: 6b 0a 2a 2a 20 73 74 61 74 65 2e 0a 2a 2f 0a 23  k.** state..*/.#
9cb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
9cc0: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 30  M_UNLOCK       0
9cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9ce0: 53 48 4d 5f 52 45 41 44 5f 50 52 45 46 49 58 20  SHM_READ_PREFIX 
9cf0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
9d00: 45 5f 53 48 4d 5f 52 45 41 44 5f 46 55 4c 4c 20  E_SHM_READ_FULL 
9d10: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
9d20: 49 54 45 5f 53 48 4d 5f 57 52 49 54 45 20 20 20  ITE_SHM_WRITE   
9d30: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
9d40: 51 4c 49 54 45 5f 53 48 4d 5f 50 45 4e 44 49 4e  QLITE_SHM_PENDIN
9d50: 47 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  G      4.#define
9d60: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 43 48 45 43   SQLITE_SHM_CHEC
9d70: 4b 50 4f 49 4e 54 20 20 20 35 0a 23 64 65 66 69  KPOINT   5.#defi
9d80: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52 45  ne SQLITE_SHM_RE
9d90: 43 4f 56 45 52 20 20 20 20 20 20 36 0a 23 64 65  COVER      6.#de
9da0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
9db0: 51 55 45 52 59 20 20 20 20 20 20 20 20 28 2d 31  QUERY        (-1
9dc0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
9dd0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
9de0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
9df0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
9e00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9e10: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
9e20: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
9e30: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
9e40: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
9e50: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
9e60: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
9e70: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
9e80: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
9e90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9ea0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
9eb0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
9ec0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
9ed0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
9ee0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
9ef0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
9f00: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
9f10: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
9f20: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
9f30: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
9f40: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
9f50: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
9f60: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
9f70: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
9f80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9f90: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
9fa0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
9fb0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
9fc0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
9fd0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
9fe0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
9ff0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
a000: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
a010: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
a020: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
a030: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
a040: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
a050: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
a060: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a070: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
a080: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
a090: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
a0a0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
a0b0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
a0c0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
a0d0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
a0e0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
a0f0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
a100: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
a110: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
a120: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
a130: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
a140: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
a150: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
a160: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
a170: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
a180: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
a190: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
a1a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
a1b0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
a1c0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
a1d0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
a1e0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
a1f0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
a200: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
a210: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
a220: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
a230: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
a240: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
a250: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
a260: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
a270: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a280: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
a290: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
a2a0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
a2b0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
a2c0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
a2d0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
a2e0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
a2f0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
a300: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
a310: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
a320: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
a330: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
a340: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
a350: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
a360: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
a370: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
a380: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
a390: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
a3a0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
a3b0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
a3c0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
a3d0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
a3e0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
a3f0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
a400: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
a410: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
a420: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
a430: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
a440: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a450: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
a460: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
a470: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
a480: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
a490: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
a4a0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
a4b0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
a4c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
a4d0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
a4e0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
a4f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
a500: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a510: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
a520: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
a530: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
a540: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
a550: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
a560: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
a570: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
a580: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
a590: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a5a0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
a5b0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
a5c0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
a5d0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
a5e0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
a5f0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
a600: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
a610: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
a620: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
a630: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
a640: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
a650: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
a660: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
a670: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
a680: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
a690: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
a6a0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
a6b0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
a6c0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
a6d0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
a6e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a6f0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
a700: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
a710: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
a720: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
a730: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
a740: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
a750: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
a760: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
a770: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
a780: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
a790: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
a7a0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
a7b0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
a7c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a7d0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
a7e0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
a7f0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
a800: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
a810: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
a820: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
a830: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
a840: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
a850: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
a860: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
a870: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
a880: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
a890: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
a8a0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
a8b0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
a8c0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
a8d0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
a8e0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
a8f0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
a900: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
a910: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
a920: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
a930: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
a940: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
a950: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a960: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
a970: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
a980: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
a990: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
a9a0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
a9b0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
a9c0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
a9d0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
a9e0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
a9f0: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
aa00: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
aa10: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
aa20: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
aa30: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
aa40: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
aa50: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
aa60: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
aa70: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
aa80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
aa90: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
aaa0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
aab0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
aac0: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
aad0: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
aae0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
aaf0: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
ab00: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
ab10: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
ab20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ab30: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
ab40: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
ab50: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ab60: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
ab70: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
ab80: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
ab90: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
aba0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
abb0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
abc0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
abd0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
abe0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
abf0: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
ac00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
ac10: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
ac20: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
ac30: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
ac40: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
ac50: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
ac60: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
ac70: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
ac80: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
ac90: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
aca0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
acb0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
acc0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
acd0: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
ace0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
acf0: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
ad00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ad10: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
ad20: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
ad30: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
ad40: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
ad50: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
ad60: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
ad70: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
ad80: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
ad90: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
ada0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
adb0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
adc0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
add0: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
ade0: 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
adf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ae00: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
ae10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
ae20: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
ae30: 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
ae40: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
ae50: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
ae60: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
ae70: 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
ae80: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
ae90: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
aea0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
aeb0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
aec0: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
aed0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
aee0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
aef0: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
af00: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
af10: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
af20: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
af30: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
af40: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
af50: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
af60: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
af70: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
af80: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
af90: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
afa0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
afb0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
afc0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
afd0: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
afe0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
aff0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
b000: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
b010: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
b020: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
b030: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
b040: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
b050: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
b060: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
b070: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
b080: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
b090: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
b0a0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
b0b0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
b0c0: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
b0d0: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
b0e0: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
b0f0: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
b100: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b110: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
b120: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
b130: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
b140: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
b150: 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
b160: 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
b170: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
b180: 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
b190: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
b1a0: 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
b1b0: 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
b1c0: 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
b1d0: 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
b1e0: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
b1f0: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
b200: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
b210: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
b220: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
b230: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
b240: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
b250: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
b260: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
b270: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
b280: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
b290: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
b2a0: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
b2b0: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
b2c0: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
b2d0: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
b2e0: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
b2f0: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
b300: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
b310: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
b320: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
b330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
b340: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
b350: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
b360: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
b370: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
b380: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
b390: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
b3a0: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
b3b0: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
b3c0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
b3d0: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
b3e0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
b3f0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
b400: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
b410: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
b420: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
b430: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
b440: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
b450: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
b460: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
b470: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
b480: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b490: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
b4a0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
b4b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
b4c0: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
b4d0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
b4e0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
b4f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
b500: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
b510: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
b520: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b530: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
b540: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
b550: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
b560: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
b570: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
b580: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
b590: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
b5a0: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b5b0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
b5c0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
b5d0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
b5e0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
b5f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
b600: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
b610: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
b620: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
b630: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
b640: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
b650: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
b660: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
b670: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
b680: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
b690: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
b6a0: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
b6b0: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
b6c0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
b6d0: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
b6e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
b6f0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
b700: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
b710: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
b720: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
b730: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
b740: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
b750: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
b760: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
b770: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
b780: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
b790: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
b7a0: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
b7b0: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
b7c0: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
b7d0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
b7e0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
b7f0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
b800: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
b810: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
b820: 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
b830: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
b840: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
b850: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
b860: 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
b870: 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
b880: 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
b890: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
b8a0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
b8b0: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
b8c0: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
b8d0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
b8e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
b8f0: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
b900: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
b910: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
b920: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
b930: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
b940: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b950: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
b960: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
b970: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
b980: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
b990: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
b9a0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
b9b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
b9c0: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
b9d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b9e0: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
b9f0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
ba00: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
ba10: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
ba20: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
ba30: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
ba40: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
ba50: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
ba60: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
ba70: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
ba80: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
ba90: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
baa0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
bab0: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
bac0: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
bad0: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
bae0: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
baf0: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
bb00: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
bb10: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
bb20: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
bb30: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
bb40: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
bb50: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
bb60: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
bb70: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
bb80: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
bb90: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
bba0: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
bbb0: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
bbc0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
bbd0: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
bbe0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
bbf0: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
bc00: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
bc10: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
bc20: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
bc30: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
bc40: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
bc50: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
bc60: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
bc70: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
bc80: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
bc90: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
bca0: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
bcb0: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
bcc0: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
bcd0: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
bce0: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
bcf0: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
bd00: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
bd10: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
bd20: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
bd30: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
bd40: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
bd50: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
bd60: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
bd70: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
bd80: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
bd90: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
bda0: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
bdb0: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
bdc0: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
bdd0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
bde0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
bdf0: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
be00: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
be10: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
be20: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
be30: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
be40: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
be50: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
be60: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
be70: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
be80: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
be90: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
bea0: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
beb0: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
bec0: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
bed0: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
bee0: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
bef0: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
bf00: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
bf10: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
bf20: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
bf30: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
bf40: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
bf50: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
bf60: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
bf70: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
bf80: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
bf90: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
bfa0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
bfb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
bfc0: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
bfd0: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
bfe0: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
bff0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
c000: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
c010: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
c020: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
c030: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
c040: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
c050: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
c060: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
c070: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
c080: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
c090: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
c0a0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
c0b0: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
c0c0: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
c0d0: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
c0e0: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
c0f0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
c100: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
c110: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
c120: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
c130: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
c140: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
c150: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
c160: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
c170: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
c180: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
c190: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
c1a0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
c1b0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
c1c0: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
c1d0: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
c1e0: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
c1f0: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
c200: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
c210: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
c220: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
c230: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
c240: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
c250: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
c260: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
c270: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
c280: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
c290: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
c2a0: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
c2b0: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
c2c0: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
c2d0: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
c2e0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
c2f0: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
c300: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
c310: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
c320: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
c330: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
c340: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
c350: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
c360: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
c370: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
c380: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
c390: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
c3a0: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
c3b0: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
c3c0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
c3d0: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
c3e0: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
c3f0: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
c400: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
c410: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
c420: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
c430: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
c440: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
c450: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
c460: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
c470: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
c480: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
c490: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
c4a0: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
c4b0: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
c4c0: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
c4d0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
c4e0: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
c4f0: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
c500: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
c510: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
c520: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
c530: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
c540: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
c550: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
c560: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
c570: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
c580: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
c590: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
c5a0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
c5b0: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
c5c0: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
c5d0: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
c5e0: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
c5f0: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
c600: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
c610: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
c620: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
c630: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
c640: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
c650: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
c660: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
c670: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
c680: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
c690: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
c6a0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
c6b0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c6c0: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
c6d0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
c6e0: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
c6f0: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
c700: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
c710: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
c720: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
c730: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
c740: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
c750: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
c760: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
c770: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
c780: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
c790: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
c7a0: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
c7b0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
c7c0: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
c7d0: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
c7e0: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
c7f0: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
c800: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
c810: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
c820: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
c830: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
c840: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
c850: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
c860: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
c870: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
c880: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
c890: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
c8a0: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
c8b0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
c8c0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
c8d0: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
c8e0: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
c8f0: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
c900: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
c910: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
c920: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
c930: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
c940: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
c950: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
c960: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
c970: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c980: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
c990: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
c9a0: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
c9b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
c9c0: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
c9d0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
c9e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
c9f0: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
ca00: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
ca10: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
ca20: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
ca30: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
ca40: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
ca50: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
ca60: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
ca70: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
ca80: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
ca90: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
caa0: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
cab0: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
cac0: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
cad0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
cae0: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
caf0: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
cb00: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
cb10: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
cb20: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
cb30: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cb40: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
cb50: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
cb60: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
cb70: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
cb80: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
cb90: 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
cba0: 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
cbb0: 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
cbc0: 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
cbd0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
cbe0: 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
cbf0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
cc00: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
cc10: 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
cc20: 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
cc30: 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
cc40: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
cc50: 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
cc60: 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
cc70: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
cc80: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
cc90: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
cca0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ccb0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ccc0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ccd0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
cce0: 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
ccf0: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
cd00: 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
cd10: 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
cd20: 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
cd30: 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
cd40: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
cd50: 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
cd60: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
cd70: 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
cd80: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
cd90: 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
cda0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
cdb0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
cdc0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
cdd0: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
cde0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
cdf0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
ce00: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
ce10: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
ce20: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
ce30: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
ce40: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
ce50: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
ce60: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
ce70: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
ce80: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
ce90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
cea0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
ceb0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
cec0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
ced0: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
cee0: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
cef0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
cf00: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
cf10: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
cf20: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
cf30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
cf40: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
cf50: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
cf60: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
cf70: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
cf80: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
cf90: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
cfa0: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
cfb0: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
cfc0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
cfd0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
cfe0: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
cff0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
d000: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
d010: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
d020: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
d030: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
d040: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
d050: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
d060: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
d070: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
d080: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
d090: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d0a0: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
d0b0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
d0c0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
d0d0: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
d0e0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
d0f0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d100: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
d110: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d120: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
d130: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
d140: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
d150: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
d160: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
d170: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
d180: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
d190: 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
d1a0: 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
d1b0: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
d1c0: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
d1d0: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
d1e0: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
d1f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
d200: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
d210: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d220: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
d230: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
d240: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
d250: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
d260: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
d270: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
d280: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
d290: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
d2a0: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
d2b0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
d2c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d2d0: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
d2e0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
d2f0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
d300: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
d310: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
d320: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d330: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
d340: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
d350: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
d360: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
d370: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
d380: 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
d390: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
d3a0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
d3b0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
d3c0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
d3d0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
d3e0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
d3f0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
d400: 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
d410: 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
d420: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
d430: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d440: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
d450: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
d460: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
d470: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
d480: 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
d490: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
d4a0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d4b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
d4c0: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
d4d0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
d4e0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
d4f0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
d500: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
d510: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
d520: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
d530: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
d540: 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
d550: 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
d560: 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
d570: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
d580: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
d590: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
d5a0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
d5b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d5c0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
d5d0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
d5e0: 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
d5f0: 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
d600: 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
d610: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
d620: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
d630: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
d640: 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
d650: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
d660: 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
d670: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
d680: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
d690: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
d6a0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d6b0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d6c0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d6d0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d6e0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d6f0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
d700: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
d710: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
d720: 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
d730: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
d740: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
d750: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
d760: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d770: 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
d780: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
d790: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
d7a0: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
d7b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d7c0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
d7d0: 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
d7e0: 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
d7f0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
d800: 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
d810: 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
d820: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
d830: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d840: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
d850: 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
d860: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
d870: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
d880: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
d890: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
d8a0: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
d8b0: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
d8c0: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
d8d0: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
d8e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d8f0: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
d900: 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
d910: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
d920: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
d930: 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
d940: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
d950: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
d960: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
d970: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
d980: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
d990: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
d9a0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
d9b0: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
d9c0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
d9d0: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
d9e0: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
d9f0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
da00: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
da10: 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
da20: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
da30: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
da40: 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
da50: 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
da60: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
da70: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
da80: 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
da90: 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
daa0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
dab0: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
dac0: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
dad0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
dae0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
daf0: 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
db00: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
db10: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
db20: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
db30: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
db40: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
db50: 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
db60: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
db70: 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
db80: 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
db90: 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
dba0: 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
dbb0: 63 68 20 74 68 65 20 73 63 72 61 63 68 20 61 6c  ch the scrach al
dbc0: 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
dbd0: 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
dbe0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
dbf0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
dc00: 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
dc10: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
dc20: 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
dc30: 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65  ations (N).  The
dc40: 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20   sz.** argument 
dc50: 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70  must be a multip
dc60: 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a  le of 16. The sz
dc70: 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c   parameter shoul
dc80: 64 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73  d be a few bytes
dc90: 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20  .** larger than 
dca0: 74 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74  the actual scrat
dcb0: 63 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ch space require
dcc0: 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61  d due to interna
dcd0: 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54  l overhead..** T
dce0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
dcf0: 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
dd00: 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
dd10: 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
dd20: 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
dd30: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
dd40: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
dd50: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
dd60: 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
dd70: 68 20 62 75 66 66 65 72 20 70 65 72 20 74 68 72  h buffer per thr
dd80: 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
dd90: 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
dda0: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
ddb0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
ddc0: 72 65 61 64 73 2e 20 20 5e 53 51 4c 69 74 65 20  reads.  ^SQLite 
ddd0: 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65  will.** never re
dde0: 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
ddf0: 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
de00: 6f 72 65 20 74 68 61 6e 20 36 20 74 69 6d 65 73  ore than 6 times
de10: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
de20: 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
de30: 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
de40: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 63  ds additional sc
de50: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
de60: 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20 69 73 20  ond .** what is 
de70: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
de80: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
de90: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
dea0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
deb0: 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
dec0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
ded0: 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64  mory needed.</dd
dee0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
def0: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
df00: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
df10: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
df20: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
df30: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
df40: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
df50: 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
df60: 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
df70: 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
df80: 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
df90: 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a  plemenation.  .*
dfa0: 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61  * This configura
dfb0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
dfc0: 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70  be used if an ap
dfd0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
dfe0: 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
dff0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
e000: 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
e010: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
e020: 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a  PCACHE option..*
e030: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
e040: 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  e arguments to t
e050: 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f  his option: A po
e060: 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20  inter to 8-byte 
e070: 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72  aligned.** memor
e080: 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  y, the size of e
e090: 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20  ach page buffer 
e0a0: 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75  (sz), and the nu
e0b0: 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e  mber of pages (N
e0c0: 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
e0d0: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
e0e0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
e0f0: 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
e100: 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
e110: 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
e120: 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20   512 and 32768) 
e130: 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78  plus a little ex
e140: 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tra for each.** 
e150: 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
e160: 68 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73  he page header s
e170: 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20  ize is 20 to 40 
e180: 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20  bytes depending 
e190: 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61  on.** the host a
e1a0: 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49  rchitecture.  ^I
e1b0: 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
e1c0: 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
e1d0: 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
e1e0: 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74  to make sz a lit
e1f0: 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20  tle too large.  
e200: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
e210: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
e220: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
e230: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
e240: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
e250: 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  mory..** ^SQLite
e260: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
e270: 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
e280: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e290: 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
e2a0: 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
e2b0: 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
e2c0: 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
e2d0: 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
e2e0: 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
e2f0: 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
e300: 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
e310: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
e320: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f  ovided by this o
e330: 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53  ption, then.** S
e340: 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
e350: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e360: 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f   for the additio
e370: 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63  nal storage spac
e380: 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65  e..** ^The imple
e390: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
e3a0: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  use one or more 
e3b0: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73  of the N buffers
e3c0: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d   to hold .** mem
e3d0: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
e3e0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20  nformation. The 
e3f0: 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
e400: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
e410: 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
e420: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
e430: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
e440: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
e450: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
e460: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
e470: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
e480: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
e490: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
e4a0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
e4b0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
e4c0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
e4d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
e4e0: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
e4f0: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
e500: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
e510: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
e520: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
e530: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
e540: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
e550: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e560: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
e570: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
e580: 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
e590: 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
e5a0: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
e5b0: 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
e5c0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
e5d0: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
e5e0: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
e5f0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
e600: 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
e610: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
e620: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
e630: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
e640: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
e650: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
e660: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
e670: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
e680: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
e690: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
e6a0: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
e6b0: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
e6c0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
e6d0: 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
e6e0: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
e6f0: 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
e700: 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
e710: 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
e720: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
e730: 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
e740: 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
e750: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
e760: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
e770: 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
e780: 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
e790: 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
e7a0: 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
e7b0: 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
e7c0: 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
e7d0: 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
e7e0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
e7f0: 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
e800: 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
e810: 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
e820: 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
e830: 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
e840: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e850: 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
e860: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
e870: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
e880: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
e890: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
e8a0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
e8b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e8c0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
e8d0: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
e8e0: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
e8f0: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
e900: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
e910: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
e920: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
e930: 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
e940: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
e950: 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
e960: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
e970: 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
e980: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
e990: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
e9a0: 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
e9b0: 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
e9c0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e9d0: 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
e9e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e9f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
ea00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ea10: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
ea20: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
ea30: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
ea40: 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
ea50: 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
ea60: 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
ea70: 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
ea80: 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
ea90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
eaa0: 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
eab0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
eac0: 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
ead0: 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
eae0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
eaf0: 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
eb00: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
eb10: 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
eb20: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
eb30: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
eb40: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
eb50: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
eb60: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
eb70: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
eb80: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
eb90: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
eba0: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
ebb0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
ebc0: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
ebd0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
ebe0: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
ebf0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
ec00: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
ec10: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
ec20: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
ec30: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
ec40: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
ec50: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
ec60: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
ec70: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
ec80: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
ec90: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
eca0: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
ecb0: 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
ecc0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
ecd0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
ece0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
ecf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
ed00: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
ed10: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
ed20: 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
ed30: 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
ed40: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
ed50: 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
ed60: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
ed70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
ed80: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
ed90: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
eda0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
edb0: 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
edc0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
edd0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ede0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
edf0: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
ee00: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
ee10: 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
ee20: 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
ee30: 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75  ermine the defau
ee40: 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt.** memory all
ee50: 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  ocation for the 
ee60: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
ee70: 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61   allocator on ea
ee80: 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
ee90: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
eea0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
eeb0: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
eec0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
eed0: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
eee0: 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
eef0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
ef00: 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
ef10: 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
ef20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
ef30: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73   ^(This option s
ef40: 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65  ets the.** <i>de
ef50: 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
ef60: 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
ef70: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
ef80: 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72  OOKASIDE].** ver
ef90: 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  b to [sqlite3_db
efa0: 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
efb0: 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
efc0: 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
efd0: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
efe0: 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
eff0: 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
f000: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f010: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
f020: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
f030: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
f040: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
f050: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
f060: 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
f070: 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
f080: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
f090: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
f0a0: 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
f0b0: 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
f0c0: 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
f0d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
f0e0: 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
f0f0: 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
f100: 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
f110: 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
f120: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
f130: 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
f140: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f150: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c  ONFIG_GETPCACHE<
f160: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f170: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f180: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f190: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f1a0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
f1b0: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
f1c0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
f1d0: 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
f1e0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
f1f0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
f200: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
f210: 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
f220: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
f230: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
f240: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
f250: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
f260: 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
f270: 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
f280: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
f290: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
f2a0: 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
f2b0: 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
f2c0: 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
f2d0: 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
f2e0: 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
f2f0: 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
f300: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
f310: 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
f320: 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
f330: 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
f340: 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
f350: 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
f360: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
f370: 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
f380: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
f390: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
f3a0: 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
f3b0: 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
f3c0: 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
f3d0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f3e0: 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
f3f0: 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
f400: 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
f410: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
f420: 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
f430: 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
f440: 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
f450: 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
f460: 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
f470: 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
f480: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
f490: 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
f4a0: 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
f4b0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
f4c0: 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
f4d0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
f4e0: 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
f4f0: 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
f500: 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
f510: 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
f520: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
f530: 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
f540: 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
f550: 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
f560: 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
f570: 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
f580: 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
f590: 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
f5a0: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
f5b0: 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
f5c0: 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
f5d0: 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
f5e0: 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
f5f0: 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
f600: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
f610: 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
f620: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
f630: 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
f640: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
f650: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
f660: 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
f670: 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
f680: 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
f690: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
f6a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f6b0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
f6c0: 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
f6d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f6e0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
f6f0: 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
f700: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f710: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
f720: 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
f730: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
f740: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
f750: 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
f760: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f770: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f780: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
f790: 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
f7a0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f7b0: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
f7c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
f7d0: 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
f7e0: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
f7f0: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
f800: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f810: 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
f820: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
f830: 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
f840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f850: 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
f860: 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
f870: 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
f880: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f890: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
f8a0: 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
f8b0: 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
f8c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
f8d0: 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
f8e0: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
f8f0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
f900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f910: 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
f920: 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
f930: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
f940: 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
f950: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
f960: 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
f970: 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
f980: 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
f990: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
f9a0: 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
f9b0: 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
f9c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
f9d0: 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
f9e0: 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
f9f0: 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  e_methods* */.#d
fa00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
fa10: 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
fa20: 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   15  /* sqlite3_
fa30: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20  pcache_methods* 
fa40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
fa50: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
fa60: 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
fa70: 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a  nc, void* */../*
fa80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
fa90: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
faa0: 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
fab0: 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
fac0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
fad0: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
fae0: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
faf0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
fb00: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
fb10: 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
fb20: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
fb30: 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
fb40: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
fb50: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
fb60: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fb70: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
fb80: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
fb90: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
fba0: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
fbb0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
fbc0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
fbd0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
fbe0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
fbf0: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
fc00: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
fc10: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
fc20: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
fc30: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
fc40: 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
fc50: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
fc60: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
fc70: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
fc80: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
fc90: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
fca0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
fcb0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
fcc0: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
fcd0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
fce0: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
fcf0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
fd00: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
fd10: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
fd20: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
fd30: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
fd40: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
fd50: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
fd60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
fd70: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
fd80: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
fd90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
fda0: 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
fdb0: 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
fdc0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
fdd0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
fde0: 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
fdf0: 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72  nter to an memor
fe00: 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
fe10: 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
fe20: 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
fe30: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
fe40: 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
fe50: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
fe60: 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
fe70: 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
fe80: 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
fe90: 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
fea0: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
feb0: 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
fec0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
fed0: 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
fee0: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
fef0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
ff00: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
ff10: 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
ff20: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
ff30: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
ff40: 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
ff50: 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
ff60: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ff70: 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
ff80: 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
ff90: 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
ffa0: 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
ffb0: 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
ffc0: 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
ffd0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
ffe0: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
fff0: 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
10000 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10010 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
10020 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10030 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
10040 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
10050 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
10060 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
10070 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
10080 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  .** multiple of 
10090 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53  8.  See also: [S
100a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
100b0 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a  KASIDE]</dd>.**.
100c0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
100d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
100e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
100f0 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
10100 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
10110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
10120 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
10130 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
10140 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  odes.**.** ^The 
10150 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
10160 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20  _result_codes() 
10170 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
10180 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a  or disables the.
10190 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
101a0 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
101b0 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54  re of SQLite. ^T
101c0 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
101d0 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
101e0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
101f0 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
10200 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
10210 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10220 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
10230 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c  _codes(sqlite3*,
10240 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
10250 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61  .** CAPI3REF: La
10260 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a  st Insert Rowid.
10270 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
10280 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74  y in an SQLite t
10290 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75  able has a uniqu
102a0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
102b0 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
102c0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
102d0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
102e0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
102f0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
10300 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
10310 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
10320 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
10330 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
10340 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
10350 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
10360 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
10370 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
10380 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
10390 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
103a0 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
103b0 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
103c0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
103d0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
103e0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
103f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
10400 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
10410 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d  [rowid] of the m
10420 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75  ost recent.** su
10430 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
10440 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  ] into the datab
10450 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61  ase from the [da
10460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10470 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10480 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49  st argument.  ^I
10490 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
104a0 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76  [INSERT]s.** hav
104b0 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
104c0 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65  on that database
104d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
104e0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
104f0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
10500 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
10510 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74  hin a trigger, t
10520 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  hen the [rowid] 
10530 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
10540 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e  ** row is return
10550 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
10560 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ne as long as th
10570 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e  e trigger is run
10580 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63  ning..** But onc
10590 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65  e the trigger te
105a0 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61  rminates, the va
105b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
105c0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
105d0 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c  reverts to the l
105e0 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74  ast value insert
105f0 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  ed before the tr
10600 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a  igger fired.)^.*
10610 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
10620 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
10630 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
10640 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
10650 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
10660 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
10670 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
10680 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
10690 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
106a0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
106b0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
106c0 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
106d0 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
106e0 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
106f0 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
10700 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
10710 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
10720 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
10730 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
10740 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
10750 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
10760 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
10770 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
10780 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
10790 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
107a0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
107b0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
107c0 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
107d0 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
107e0 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
107f0 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
10800 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
10810 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
10820 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
10830 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
10840 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
10850 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
10860 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
10870 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
10880 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
10890 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
108a0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
108b0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
108c0 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
108d0 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
108e0 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
108f0 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
10900 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
10910 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
10920 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
10930 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
10940 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
10950 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
10960 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
10970 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
10980 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
10990 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
109a0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
109b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
109c0 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
109d0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
109e0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
109f0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
10a00 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
10a10 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
10a20 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
10a30 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
10a40 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
10a50 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
10a60 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
10a70 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
10a80 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  rowid]..*/.sqlit
10a90 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
10aa0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
10ab0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
10ac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10ad0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
10ae0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
10af0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
10b00 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
10b10 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
10b20 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
10b30 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
10b40 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
10b50 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
10b60 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
10b70 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
10b80 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
10b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10ba0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
10bb0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
10bc0 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63  ter..** ^(Only c
10bd0 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20  hanges that are 
10be0 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69  directly specifi
10bf0 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52  ed by the [INSER
10c00 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a  T], [UPDATE],.**
10c10 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
10c20 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74  tement are count
10c30 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63  ed.  Auxiliary c
10c40 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
10c50 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20  .** triggers or 
10c60 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
10c70 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  ions] are not co
10c80 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65  unted.)^ Use the
10c90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  .** [sqlite3_tot
10ca0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
10cb0 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74  nction to find t
10cc0 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
10cd0 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e  of changes.** in
10ce0 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
10cf0 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
10d00 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b  rs and foreign k
10d10 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  ey actions..**.*
10d20 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  * ^Changes to a 
10d30 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69  view that are si
10d40 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49  mulated by an [I
10d50 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
10d60 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  r].** are not co
10d70 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61  unted.  Only rea
10d80 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20  l table changes 
10d90 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
10da0 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e  ** ^(A "row chan
10db0 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
10dc0 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
10dd0 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
10de0 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
10df0 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
10e00 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
10e10 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
10e20 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
10e30 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
10e40 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   of [REPLACE] co
10e50 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
10e60 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
10e70 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
10e80 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d  ng, [DROP TABLE]
10e90 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
10ea0 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
10eb0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
10ec0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
10ed0 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  es.)^.**.** A "t
10ee0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
10ef0 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
10f00 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
10f10 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
10f20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
10f30 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49  of a [CREATE TRI
10f40 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e  GGER | trigger].
10f50 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74   .** Most SQL st
10f60 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20  atements are.** 
10f70 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64  evaluated outsid
10f80 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72  e of any trigger
10f90 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22  .  This is the "
10fa0 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72  top level".** tr
10fb0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20  igger context.  
10fc0 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72  If a trigger fir
10fd0 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  es from the top 
10fe0 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20  level, a.** new 
10ff0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20  trigger context 
11000 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74  is entered for t
11010 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74  he duration of t
11020 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67  hat one.** trigg
11030 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73  er.  Subtriggers
11040 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65   create subconte
11050 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75  xts for their du
11060 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ration..**.** ^C
11070 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
11080 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
11090 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
110a0 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
110b0 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
110c0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
110d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
110e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
110f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
11100 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
11110 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
11120 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
11130 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
11140 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
11150 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
11160 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
11170 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20  .** ^Thus, when 
11180 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
11190 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20  top level, this 
111a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
111b0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
111c0 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  f changes in the
111d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
111e0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
111f0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61  DELETE.** that a
11200 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20  lso occurred at 
11210 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20  the top level.  
11220 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64  ^(Within the bod
11230 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a  y of a trigger,.
11240 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ** the sqlite3_c
11250 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61  hanges() interfa
11260 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ce can be called
11270 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
11280 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65  ber of.** change
11290 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
112a0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
112b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
112c0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
112d0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
112e0 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73  he body of the s
112f0 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20  ame trigger..** 
11300 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d  However, the num
11310 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65  ber returned doe
11320 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
11330 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20  anges.** caused 
11340 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73  by subtriggers s
11350 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20  ince those have 
11360 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78  their own contex
11370 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
11380 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
11390 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
113a0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
113b0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
113c0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
113d0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
113e0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
113f0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
11400 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
11410 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
11420 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
11430 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
11440 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
11450 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
11460 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
11470 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
11480 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
11490 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
114a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68  /.int sqlite3_ch
114b0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
114c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
114d0 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f  : Total Number O
114e0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
114f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
11500 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
11510 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63   number of row c
11520 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
11530 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55   [INSERT],.** [U
11540 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
11550 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  E] statements si
11560 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
11570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
11580 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54  s opened..** ^(T
11590 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65  he count returne
115a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
115b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63  al_changes() inc
115c0 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
115d0 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43  s.** from all [C
115e0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
115f0 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74  trigger] context
11600 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61  s and changes ma
11610 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67  de by.** [foreig
11620 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20  n key actions]. 
11630 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20  However,.** the 
11640 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
11650 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75  nclude changes u
11660 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
11670 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
11680 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f  raints,.** do ro
11690 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54  llbacks or ABORT
116a0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20   processing, or 
116b0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f  [DROP TABLE] pro
116c0 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a  cessing.  The.**
116d0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
116e0 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20  include rows of 
116f0 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20  views that fire 
11700 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
11710 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75  rigger],.** thou
11720 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41  gh if the INSTEA
11730 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b  D OF trigger mak
11740 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74  es changes of it
11750 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61  s own, those cha
11760 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75  nges .** are cou
11770 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20  nted.)^.** ^The 
11780 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11790 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
117a0 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e   counts the chan
117b0 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a  ges as soon as.*
117c0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  * the statement 
117d0 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20  that makes them 
117e0 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  is completed (wh
117f0 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
11800 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61   handle.** is pa
11810 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
11820 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
11830 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
11840 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
11850 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
11860 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
11870 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
11880 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
11890 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f  ma], and the [to
118a0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51  tal_changes() SQ
118b0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
118c0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
118d0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
118e0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
118f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11900 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
11910 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11920 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
11930 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
11940 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ue.** returned i
11950 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
11960 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
11970 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
11980 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
11990 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
119a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74  ** CAPI3REF: Int
119b0 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75  errupt A Long-Ru
119c0 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a  nning Query.**.*
119d0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
119e0 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
119f0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
11a00 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
11a10 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
11a20 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
11a30 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
11a40 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
11a50 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
11a60 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
11a70 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
11a80 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
11a90 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
11aa0 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
11ab0 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
11ac0 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
11ad0 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
11ae0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
11af0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
11b00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
11b10 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
11b20 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
11b30 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
11b40 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
11b50 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
11b60 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
11b70 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
11b80 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
11b90 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
11ba0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11bb0 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
11bc0 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
11bd0 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
11be0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11bf0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
11c00 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
11c10 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
11c20 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
11c30 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
11c40 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11c50 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
11c60 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
11c70 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
11c80 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
11c90 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
11ca0 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
11cb0 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
11cc0 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
11cd0 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
11ce0 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
11cf0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
11d00 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
11d10 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
11d20 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
11d30 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
11d40 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
11d50 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
11d60 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
11d70 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
11d80 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
11d90 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
11da0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
11db0 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
11dc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
11dd0 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
11de0 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
11df0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
11e00 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
11e10 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
11e20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11e30 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
11e40 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
11e50 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
11e60 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
11e70 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
11e80 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
11e90 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
11ea0 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
11eb0 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
11ec0 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
11ed0 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
11ee0 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
11ef0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
11f00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11f10 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
11f20 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
11f30 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
11f40 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
11f50 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
11f60 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
11f70 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
11f80 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
11f90 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
11fa0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
11fb0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11fc0 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
11fd0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
11fe0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
11ff0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
12000 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
12010 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
12020 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
12030 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
12040 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
12050 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
12060 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
12070 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
12080 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
12090 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
120a0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
120b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
120c0 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
120d0 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
120e0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
120f0 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
12100 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
12110 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
12120 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
12130 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a  ent Is Complete.
12140 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
12150 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20  ines are useful 
12160 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c  during command-l
12170 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74  ine input to det
12180 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a  ermine if the.**
12190 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72   currently enter
121a0 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f  ed text seems to
121b0 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65   form a complete
121c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f   SQL statement o
121d0 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e  r.** if addition
121e0 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64  al input is need
121f0 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e  ed before sendin
12200 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a  g the text into.
12210 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61  ** SQLite for pa
12220 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72  rsing.  ^These r
12230 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31  outines return 1
12240 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
12250 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
12260 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
12270 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
12280 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73   ^A statement is
12290 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
122a0 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
122b0 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
122c0 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
122d0 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20  is not a prefix 
122e0 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72  of a.** well-for
122f0 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47  med CREATE TRIGG
12300 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  ER statement.  ^
12310 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20  Semicolons that 
12320 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74  are embedded wit
12330 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69  hin.** string li
12340 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64  terals or quoted
12350 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65   identifier name
12360 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72  s or comments ar
12370 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e  e not.** indepen
12380 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65  dent tokens (the
12390 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68  y are part of th
123a0 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68  e token in which
123b0 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62   they are.** emb
123c0 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20  edded) and thus 
123d0 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
123e0 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d  a statement term
123f0 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73  inator.  ^Whites
12400 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d  pace.** and comm
12410 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77  ents that follow
12420 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63   the final semic
12430 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64  olon are ignored
12440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
12450 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30  outines return 0
12460 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
12470 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e  t is incomplete.
12480 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72    ^If a.** memor
12490 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
124a0 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  ls, then SQLITE_
124b0 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65  NOMEM is returne
124c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
124d0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
124e0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
124f0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
12500 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
12510 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
12520 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
12530 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20  .** ^(If SQLite 
12540 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69  has not been ini
12550 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b  tialized using [
12560 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12570 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20  ze()] prior .** 
12580 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  to invoking sqli
12590 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
125a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e   then sqlite3_in
125b0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
125c0 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74  voked.** automat
125d0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
125e0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20  3_complete16(). 
125f0 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c   If that initial
12600 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a  ization fails,.*
12610 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
12620 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
12630 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
12640 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65  ) will be non-ze
12650 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73  ro.** regardless
12660 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
12670 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c  ot the input SQL
12680 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a   is complete.)^.
12690 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
126a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
126b0 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20  lete()] must be 
126c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
126d0 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e  d.** UTF-8 strin
126e0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  g..**.** The inp
126f0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
12700 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
12710 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
12720 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
12730 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
12740 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f  e byte order..*/
12750 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
12760 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
12770 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   *sql);.int sqli
12780 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
12790 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
127a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
127b0 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
127c0 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
127d0 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
127e0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
127f0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
12800 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
12810 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
12820 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
12830 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
12840 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
12850 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
12860 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
12870 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
12880 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
12890 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
128a0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
128b0 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
128c0 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
128d0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
128e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
128f0 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
12900 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
12910 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
12920 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
12930 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
12940 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
12950 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
12960 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
12970 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
12980 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
12990 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
129a0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
129b0 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
129c0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
129d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
129e0 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
129f0 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
12a00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12a10 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
12a20 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
12a30 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
12a40 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
12a50 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
12a60 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
12a70 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
12a80 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
12a90 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
12aa0 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
12ab0 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
12ac0 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
12ad0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
12ae0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
12af0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
12b00 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
12b10 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
12b20 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
12b30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
12b40 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
12b50 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
12b60 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
12b70 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
12b80 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
12b90 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
12ba0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
12bb0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
12bc0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
12bd0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
12be0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
12bf0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
12c00 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
12c10 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
12c20 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
12c30 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
12c40 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
12c50 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
12c60 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
12c70 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
12c80 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
12c90 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
12ca0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
12cb0 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
12cc0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
12cd0 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
12ce0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
12cf0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
12d00 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
12d10 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
12d20 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
12d30 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
12d40 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
12d50 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
12d60 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
12d70 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
12d80 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
12d90 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
12da0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
12db0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
12dc0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
12dd0 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
12de0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
12df0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
12e00 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
12e10 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
12e20 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
12e30 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
12e40 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
12e50 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
12e60 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
12e70 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
12e80 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
12e90 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
12ea0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
12eb0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
12ec0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
12ed0 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
12ee0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
12ef0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
12f00 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
12f10 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
12f20 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
12f30 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
12f40 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
12f50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
12f60 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
12f70 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
12f80 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
12f90 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
12fa0 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
12fb0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
12fc0 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
12fd0 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
12fe0 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
12ff0 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
13000 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
13010 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
13020 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
13030 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
13040 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
13050 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
13060 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
13070 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
13080 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
13090 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
130a0 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
130b0 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
130c0 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
130d0 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
130e0 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
130f0 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
13100 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
13110 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
13120 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
13130 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
13140 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
13150 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
13160 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
13170 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
13180 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
13190 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
131a0 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
131b0 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
131c0 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
131d0 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
131e0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
131f0 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
13200 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
13210 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
13220 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
13230 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
13240 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
13250 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
13260 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
13270 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13280 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
13290 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
132a0 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
132b0 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
132c0 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
132d0 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
132e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
132f0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
13300 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
13310 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
13320 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
13330 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
13340 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
13350 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
13360 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
13370 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
13380 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
13390 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
133a0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
133b0 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
133c0 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
133d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
133e0 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
133f0 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
13400 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
13410 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
13420 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
13430 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
13440 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
13450 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
13460 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
13470 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
13480 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
13490 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
134a0 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
134b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
134c0 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
134d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
134e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
134f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
13500 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
13510 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
13520 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
13530 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
13540 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13550 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
13560 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
13570 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
13580 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
13590 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
135a0 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
135b0 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
135c0 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
135d0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
135e0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
135f0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
13600 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
13610 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
13620 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
13630 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
13640 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
13650 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
13660 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
13670 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
13680 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
13690 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
136a0 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
136b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
136c0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
136d0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
136e0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
136f0 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
13700 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
13710 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
13720 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
13730 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
13740 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
13750 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
13760 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
13770 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
13780 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
13790 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
137a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
137b0 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
137c0 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
137d0 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
137e0 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
137f0 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
13800 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
13810 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
13820 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
13830 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
13840 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
13850 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
13860 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
13870 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
13880 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
13890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
138a0 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
138b0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
138c0 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65  Queries.**.** De
138d0 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
138e0 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
138f0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
13900 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
13910 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
13920 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
13930 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
13940 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
13950 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
13960 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
13970 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
13980 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
13990 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
139a0 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
139b0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
139c0 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
139d0 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
139e0 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
139f0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
13a00 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
13a10 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
13a20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
13a30 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
13a40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
13a50 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
13a60 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
13a70 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
13a80 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
13a90 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
13aa0 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
13ab0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
13ac0 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
13ad0 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
13ae0 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
13af0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
13b00 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
13b10 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
13b20 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
13b30 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
13b40 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
13b50 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
13b60 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
13b70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
13b80 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
13b90 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
13ba0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
13bb0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
13bc0 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
13bd0 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
13be0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
13bf0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
13c00 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
13c10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
13c20 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
13c30 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
13c40 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
13c50 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
13c60 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
13c70 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
13c80 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
13c90 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
13ca0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
13cb0 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
13cc0 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
13cd0 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
13ce0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
13cf0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  able()]..**.** A
13d00 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
13d10 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
13d20 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
13d30 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
13d40 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
13d50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13d60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
13d70 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
13d80 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
13d90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
13da0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
13db0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
13dc0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
13dd0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
13de0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
13df0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
13e00 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
13e10 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
13e20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
13e30 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
13e40 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
13e50 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
13e60 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
13e70 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
13e80 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
13e90 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
13ea0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
13eb0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
13ec0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
13ed0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
13ee0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
13ef0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13f00 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
13f10 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
13f20 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
13f30 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
13f40 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
13f50 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
13f60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13f70 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
13f80 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
13f90 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
13fa0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
13fb0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
13fc0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
13fd0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
13fe0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
13ff0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
14000 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
14010 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14030 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14040 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
14050 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
14060 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
14070 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
14080 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
14090 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
140a0 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
140b0 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
140c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
140d0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
140e0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
140f0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
14100 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
14110 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
14120 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
14130 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
14140 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
14150 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
14160 69 74 20 73 68 6f 75 6c 64 20 70 61 73 73 20 74  it should pass t
14170 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
14180 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
14190 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
141a0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
141b0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
141c0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
141d0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
141e0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
141f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14200 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
14210 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
14220 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
14230 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
14240 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
14250 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
14260 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
14270 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
14280 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
14290 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
142a0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
142b0 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
142c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
142d0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
142e0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
142f0 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
14300 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
14310 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
14320 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
14330 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
14340 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
14350 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
14360 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
14370 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
14380 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
14390 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
143a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
143b0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
143c0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
143d0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
143e0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
143f0 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
14400 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
14410 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
14420 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
14430 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
14440 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
14450 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
14460 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
14470 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
14480 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
14490 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
144a0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
144b0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
144c0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
144d0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
144e0 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
144f0 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
14500 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
14510 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
14520 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
14530 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
14540 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
14550 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
14560 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
14570 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
14580 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
14590 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
145a0 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
145b0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
145c0 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
145d0 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
145e0 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
145f0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
14600 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
14610 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
14620 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
14630 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
14640 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
14650 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14660 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
14670 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
14680 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
14690 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
146a0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
146b0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
146c0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
146d0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
146e0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
146f0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
14700 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
14710 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
14720 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
14730 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
14740 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
14750 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
14760 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
14770 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
14780 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
14790 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
147a0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
147b0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
147c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
147d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
147e0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
147f0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
14800 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
14810 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ing..**.** ^(In 
14820 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14830 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
14840 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
14850 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
14860 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
14870 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
14880 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
14890 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
148a0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
148b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
148c0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
148d0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
148e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
148f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
14900 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
14910 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
14920 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
14930 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
14940 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
14950 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
14960 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
14970 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
14980 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
14990 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
149a0 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
149b0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
149c0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
149d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
149e0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
149f0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
14a00 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
14a10 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
14a20 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
14a30 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
14a40 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
14a50 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
14a60 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
14a70 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
14a80 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
14a90 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
14aa0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
14ab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
14ac0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14ad0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
14ae0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
14af0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
14b00 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
14b10 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
14b20 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
14b30 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
14b40 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
14b50 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
14b60 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
14b70 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
14b80 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
14b90 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
14ba0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
14bb0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
14bc0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
14bd0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
14be0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
14bf0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
14c00 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
14c10 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
14c20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
14c30 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  acters..**.** Th
14c40 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
14c50 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
14c60 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
14c70 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
14c80 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
14c90 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
14ca0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
14cb0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
14cc0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
14cd0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
14ce0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
14cf0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
14d00 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
14d10 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
14d20 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
14d30 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
14d40 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
14d50 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
14d60 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65  a null-terminate
14d70 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
14d80 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
14d90 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
14da0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
14db0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
14dc0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
14dd0 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
14de0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
14df0 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
14e00 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
14e10 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
14e20 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
14e30 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
14e40 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
14e50 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
14e60 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
14e70 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
14e80 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
14e90 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
14ea0 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
14eb0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14ec0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
14ed0 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
14ee0 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
14ef0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14f00 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
14f10 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
14f20 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
14f30 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
14f40 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
14f50 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
14f60 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
14f70 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
14f80 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
14f90 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
14fa0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
14fb0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
14fc0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
14fd0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
14fe0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
14ff0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15000 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
15010 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
15020 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
15030 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
15040 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
15050 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
15060 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
15070 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
15080 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15090 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
150a0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
150b0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
150c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
150d0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
150e0 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
150f0 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
15100 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
15110 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
15120 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
15130 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
15140 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15150 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
15160 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
15170 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
15180 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
15190 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
151a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
151b0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
151c0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
151d0 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
151e0 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
151f0 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
15200 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
15210 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
15220 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
15230 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
15240 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
15250 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
15260 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
15270 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
15280 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
15290 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
152a0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
152b0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
152c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
152d0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
152e0 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
152f0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
15300 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
15310 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
15320 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
15330 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
15340 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
15350 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
15360 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
15370 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
15380 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
15390 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
153a0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
153b0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
153c0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
153d0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
153e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
153f0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
15400 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
15410 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
15420 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
15430 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
15440 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
15450 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
15460 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
15470 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
15480 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
15490 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d   ^(The "%z" form
154a0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
154b0 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75  rks like "%s" bu
154c0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64  t with the.** ad
154d0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65  dition that afte
154e0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73  r the string has
154f0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63   been read and c
15500 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  opied into.** th
15510 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74  e result, [sqlit
15520 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61  e3_free()] is ca
15530 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75  lled on the inpu
15540 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63  t string.)^.*/.c
15550 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
15560 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
15570 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
15580 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
15590 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
155a0 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
155b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
155c0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
155d0 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
155e0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
155f0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
15600 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
15610 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
15620 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
15630 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
15640 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
15650 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
15660 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
15670 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
15680 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
15690 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
156a0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
156b0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
156c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
156d0 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
156e0 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
156f0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
15700 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
15710 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
15720 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
15730 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
15740 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
15750 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
15760 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
15770 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
15780 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
15790 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
157a0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
157b0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
157c0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
157d0 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
157e0 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
157f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
15800 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
15810 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
15820 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
15830 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
15840 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
15850 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
15860 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
15870 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
15880 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
15890 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
158a0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
158b0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
158c0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
158d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
158e0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
158f0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
15900 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
15910 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
15920 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
15930 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
15940 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
15950 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
15960 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
15970 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
15980 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
15990 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
159a0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
159b0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
159c0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
159d0 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
159e0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
159f0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
15a00 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
15a10 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
15a20 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
15a30 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
15a40 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
15a50 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
15a60 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
15a70 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
15a80 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
15a90 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
15aa0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
15ab0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
15ac0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
15ad0 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
15ae0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
15af0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
15b00 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
15b10 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  ^(The sqlite3_re
15b20 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
15b30 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
15b40 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
15b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15b60 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
15b70 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
15b80 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
15b90 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
15ba0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
15bb0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
15bc0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
15bd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20  ** parameter.)^ 
15be0 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70  ^ If the first p
15bf0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
15c00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
15c10 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
15c20 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
15c30 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
15c40 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
15c50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
15c60 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  ) where N is the
15c70 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15c80 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
15c90 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74  lloc()..** ^If t
15ca0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
15cb0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
15cc0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
15cd0 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
15ce0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
15cf0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
15d00 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
15d10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
15d20 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
15d30 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15d40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
15d50 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c  alloc()..** ^sql
15d60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
15d70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
15d80 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
15d90 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
15da0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
15db0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
15dc0 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
15dd0 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
15de0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
15df0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
15e00 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
15e10 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
15e20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
15e30 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
15e40 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
15e50 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
15e60 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
15e70 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
15e80 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
15e90 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
15ea0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
15eb0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
15ec0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
15ed0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
15ee0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
15ef0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
15f00 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
15f10 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
15f20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e  ite3_malloc() an
15f30 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
15f40 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  c().** is always
15f50 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
15f60 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
15f70 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  oundary..**.** I
15f80 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
15f90 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
15fa0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
15fb0 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
15fc0 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
15fd0 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
15fe0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
15ff0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
16000 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
16010 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
16020 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
16030 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
16040 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
16050 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
16060 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
16070 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
16080 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
16090 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
160a0 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
160b0 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
160c0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
160d0 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
160e0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
160f0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
16100 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
16110 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
16120 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
16130 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
16140 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
16150 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
16160 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
16170 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
16180 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16190 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
161a0 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
161b0 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
161c0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
161d0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
161e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
161f0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
16200 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
16210 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
16220 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
16230 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
16240 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16250 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
16260 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
16270 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
16280 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
16290 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
162a0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
162b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
162c0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
162d0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
162e0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
162f0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
16300 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
16310 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
16320 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
16330 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
16340 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
16350 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
16360 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
16370 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
16380 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
16390 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
163a0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
163b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
163c0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
163d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
163e0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
163f0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
16400 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
16410 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
16420 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
16430 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
16440 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
16450 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
16460 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
16470 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
16480 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
16490 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
164a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
164b0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
164c0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
164d0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
164e0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
164f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16500 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
16510 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
16520 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
16530 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
16540 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
16550 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
16560 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
16570 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16580 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
16590 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
165a0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
165b0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
165c0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
165d0 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
165e0 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
165f0 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
16600 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
16610 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
16620 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
16630 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16640 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
16650 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
16660 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
16670 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
16680 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
16690 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
166a0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
166b0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
166c0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
166d0 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
166e0 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
166f0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
16700 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
16710 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
16720 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
16730 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
16740 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
16750 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
16760 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
16770 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
16780 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
16790 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
167a0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
167b0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
167c0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
167d0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
167e0 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
167f0 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
16800 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
16810 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
16820 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
16830 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
16840 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
16850 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
16860 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
16870 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
16880 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16890 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
168a0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
168b0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
168c0 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
168d0 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
168e0 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
168f0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
16900 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
16910 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
16920 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
16930 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
16940 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
16950 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
16960 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
16970 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
16980 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
16990 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
169a0 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
169b0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
169c0 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
169d0 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
169e0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
169f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
16a00 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
16a10 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
16a20 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
16a30 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
16a40 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
16a50 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
16a60 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
16a70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
16a80 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
16a90 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
16aa0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
16ab0 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
16ac0 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
16ad0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
16ae0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
16af0 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
16b00 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
16b10 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
16b20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
16b30 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
16b40 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
16b50 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
16b60 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
16b70 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
16b80 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
16b90 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
16ba0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
16bb0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
16bc0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
16bd0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
16be0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
16bf0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
16c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16c10 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
16c20 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
16c30 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
16c40 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
16c50 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
16c60 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
16c70 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
16c80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16c90 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
16ca0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
16cb0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
16cc0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16cd0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
16ce0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
16cf0 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
16d00 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
16d10 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
16d20 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
16d30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16d40 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
16d50 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
16d60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16d70 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
16d80 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
16d90 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
16da0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
16db0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
16dc0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
16dd0 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
16de0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
16df0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16e00 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
16e10 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
16e20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
16e30 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
16e40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
16e50 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
16e60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
16e70 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
16e80 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
16e90 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
16ea0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
16eb0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
16ec0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
16ed0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
16ee0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
16ef0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
16f00 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
16f10 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
16f20 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
16f30 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
16f40 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
16f50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16f60 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
16f70 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
16f80 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
16f90 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
16fa0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
16fb0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
16fc0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16fd0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
16fe0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
16ff0 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
17000 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
17010 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
17020 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
17030 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
17040 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
17050 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
17060 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
17070 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
17080 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
17090 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
170a0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
170b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
170c0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
170d0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
170e0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
170f0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
17100 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
17110 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
17120 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
17130 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
17140 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
17150 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17160 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
17170 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
17180 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
17190 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
171a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
171b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
171c0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
171d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
171e0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
171f0 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
17200 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17210 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
17220 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
17230 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
17240 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
17250 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
17260 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
17270 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
17280 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
17290 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
172a0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
172b0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
172c0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
172d0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
172e0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
172f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
17300 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
17310 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
17320 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
17330 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
17340 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
17350 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
17360 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
17370 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
17380 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
17390 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
173a0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
173b0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
173c0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
173d0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
173e0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
173f0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
17400 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
17410 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
17420 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
17430 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
17440 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
17450 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
17460 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
17470 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
17480 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
17490 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
174a0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
174b0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
174c0 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
174d0 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
174e0 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
174f0 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
17500 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
17510 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
17520 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
17530 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
17540 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
17550 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
17560 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
17570 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
17580 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
17590 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
175a0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
175b0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
175c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
175d0 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
175e0 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
175f0 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
17600 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
17610 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
17620 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
17630 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
17640 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
17650 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
17660 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
17670 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
17680 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
17690 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
176a0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
176b0 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
176c0 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
176d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
176e0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
176f0 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
17700 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
17710 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
17720 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
17730 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
17740 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
17750 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
17760 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
17770 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
17780 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
17790 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
177a0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
177b0 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
177c0 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
177d0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
177e0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
177f0 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
17800 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
17810 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
17820 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
17830 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
17840 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
17850 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
17860 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
17870 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
17880 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
17890 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
178a0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
178b0 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
178c0 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
178d0 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
178e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
178f0 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
17900 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
17910 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
17920 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
17930 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
17940 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
17950 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
17960 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
17970 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
17980 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
17990 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
179a0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
179b0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
179c0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
179d0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
179e0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
179f0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
17a00 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
17a10 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
17a20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
17a30 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
17a40 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17a50 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
17a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17a70 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
17a80 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
17a90 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
17aa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17ab0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
17ac0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
17ad0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
17ae0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
17af0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17b00 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
17b10 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
17b20 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
17b30 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
17b40 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
17b50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
17b60 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
17b70 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
17b80 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
17b90 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
17ba0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
17bb0 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
17bc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
17bd0 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
17be0 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
17bf0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
17c00 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
17c10 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17c20 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
17c30 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
17c40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17c50 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
17c60 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
17c70 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
17c80 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
17c90 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
17ca0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
17cb0 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
17cc0 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
17cd0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
17ce0 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
17cf0 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
17d00 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
17d10 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
17d20 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
17d30 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
17d40 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
17d50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17d60 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
17d70 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
17d80 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
17d90 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
17da0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
17db0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
17dc0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
17dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17de0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
17df0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
17e00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
17e10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
17e20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17e30 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
17e40 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
17e50 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
17e60 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
17e70 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
17e80 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
17e90 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
17ea0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
17eb0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
17ec0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
17ed0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17ee0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17ef0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
17f00 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
17f10 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
17f20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
17f30 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
17f40 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
17f50 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
17f60 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
17f70 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
17f80 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
17f90 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
17fa0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
17fb0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
17fc0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
17fd0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
17fe0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
17ff0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18000 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
18010 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
18020 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
18030 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
18040 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
18050 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
18060 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
18070 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
18080 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
18090 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
180a0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
180b0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
180c0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
180d0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
180e0 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
180f0 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
18100 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
18110 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18120 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
18130 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
18140 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
18150 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
18160 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
18170 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
18180 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
18190 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
181a0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
181b0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
181c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
181d0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
181e0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
181f0 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
18200 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
18210 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
18220 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
18230 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
18240 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
18250 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18260 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
18270 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
18280 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
18290 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
182a0 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
182b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
182c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
182d0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
182e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
182f0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
18300 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
18310 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
18320 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
18330 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
18340 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
18350 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
18360 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
18370 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
18380 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
18390 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
183a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
183b0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
183c0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
183d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
183e0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
183f0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
18400 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
18410 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18430 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
18440 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
18450 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18460 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18470 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18480 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
18490 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
184a0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
184b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
184c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
184d0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
184e0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
184f0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18500 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18510 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18520 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
18530 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
18540 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
18550 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18560 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18570 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
18580 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
18590 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
185a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
185b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
185c0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
185d0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
185e0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
185f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18600 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
18610 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
18620 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
18630 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18640 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18650 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
18660 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
18670 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18680 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18690 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
186a0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
186b0 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
186c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
186d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
186e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
186f0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
18700 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
18710 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18720 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18730 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18740 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
18750 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
18760 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
18770 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18780 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18790 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
187a0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
187b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
187c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
187d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
187e0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
187f0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
18800 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
18810 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18830 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
18840 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
18850 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
18860 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18880 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
18890 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
188a0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
188b0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
188c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
188d0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
188e0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
188f0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18900 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18910 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
18920 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
18930 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
18940 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18950 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18960 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
18970 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
18980 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
18990 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
189a0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
189b0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
189c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
189d0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
189e0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
189f0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
18a00 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
18a10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18a20 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
18a30 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
18a40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18a50 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
18a60 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
18a70 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
18a80 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18a90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18aa0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
18ab0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
18ac0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18ad0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
18ae0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18af0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
18b00 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
18b10 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
18b20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18b30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18b40 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
18b50 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
18b60 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
18b70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18b80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18b90 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
18ba0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
18bb0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
18bc0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18bd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18be0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
18bf0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
18c00 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
18c10 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18c20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c30 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
18c40 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
18c50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18c60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18c70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c80 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
18c90 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
18ca0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
18cb0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
18cc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18cd0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
18ce0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
18cf0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
18d00 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
18d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18d20 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
18d30 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
18d40 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
18d50 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
18d60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
18d70 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
18d80 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
18d90 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
18da0 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
18db0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18dc0 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
18dd0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
18de0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
18df0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
18e00 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
18e10 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
18e20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
18e30 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
18e40 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
18e50 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
18e60 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
18e70 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
18e80 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
18e90 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
18ea0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
18eb0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
18ec0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
18ed0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
18ee0 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
18ef0 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
18f00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
18f10 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
18f20 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
18f30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18f40 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
18f50 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
18f60 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
18f70 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
18f80 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
18f90 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
18fa0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
18fb0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
18fc0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
18fd0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
18fe0 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
18ff0 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
19000 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
19010 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
19020 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
19030 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
19040 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
19050 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
19060 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
19070 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
19080 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19090 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
190a0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
190b0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
190c0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
190d0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
190e0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
190f0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
19100 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
19110 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
19120 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
19130 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
19140 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
19150 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
19160 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a  took to run..*/.
19170 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
19180 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
19190 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
191a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
191b0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
191c0 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
191d0 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
191e0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
191f0 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
19200 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
19210 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
19220 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
19230 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
19240 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
19250 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
19260 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
19270 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
19280 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
19290 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
192a0 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
192b0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
192c0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
192d0 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
192e0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
192f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
19300 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
19310 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
19320 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
19330 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
19340 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
19350 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
19360 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
19370 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  query..**.** ^If
19380 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
19390 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
193a0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
193b0 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
193c0 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
193d0 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
193e0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
193f0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
19400 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
19410 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
19420 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
19430 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
19440 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
19450 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
19460 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
19470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19480 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
19490 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
194a0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
194b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
194c0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
194d0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
194e0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
194f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19500 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
19510 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
19520 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
19530 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
19540 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
19550 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19560 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
19570 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
19580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19590 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
195a0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
195b0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
195c0 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
195d0 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
195e0 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20  file whose name 
195f0 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a  is given by the.
19600 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
19610 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
19620 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
19630 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
19640 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
19650 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
19660 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19670 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
19680 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
19690 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
196a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
196b0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
196c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
196d0 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
196e0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
196f0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
19700 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
19710 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
19720 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
19730 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
19740 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
19750 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
19760 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
19770 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
19780 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
19790 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
197a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
197b0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
197c0 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
197d0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
197e0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
197f0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
19800 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
19810 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
19820 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
19830 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
19840 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
19850 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
19860 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
19870 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
19880 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
19890 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
198a0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
198b0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
198c0 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
198d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
198e0 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
198f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
19900 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
19910 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
19920 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
19930 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
19940 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
19950 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
19960 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
19970 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
19980 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
19990 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
199a0 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
199b0 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
199c0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
199d0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
199e0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
199f0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
19a00 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
19a10 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
19a20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
19a30 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
19a40 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
19a50 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
19a60 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
19a70 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
19a80 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
19a90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19aa0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
19ab0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
19ac0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
19ad0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
19ae0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
19af0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
19b00 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
19b10 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
19b20 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
19b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
19b40 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
19b50 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
19b60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
19b70 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
19b80 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
19b90 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
19ba0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
19bb0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
19bc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
19bd0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
19be0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
19bf0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
19c00 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f  DCACHE],.** and/
19c10 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
19c20 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
19c30 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
19c40 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
19c50 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
19c60 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
19c70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
19c80 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
19c90 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
19ca0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
19cb0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
19cc0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
19cd0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
19ce0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
19cf0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
19d00 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
19d10 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
19d20 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
19d30 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
19d40 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
19d50 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
19d60 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
19d70 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
19d80 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
19d90 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
19da0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
19db0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
19dc0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
19dd0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
19de0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
19df0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
19e00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
19e10 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
19e20 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
19e30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
19e40 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
19e50 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
19e60 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
19e70 20 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a   creates it if.*
19e80 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
19e90 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
19ea0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
19eb0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
19ec0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
19ed0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
19ee0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
19ef0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
19f00 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
19f10 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
19f20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19f30 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
19f40 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
19f50 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
19f60 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  or one of the co
19f70 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
19f80 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a   above combined.
19f90 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
19fa0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
19fb0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
19fc0 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b  FULLMUTEX],.** [
19fd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
19fe0 45 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20  EDCACHE] and/or 
19ff0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1a000 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c  REDCACHE] flags,
1a010 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68  .** then the beh
1a020 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
1a030 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1a040 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1a050 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
1a060 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61  set, then the da
1a070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a080 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68  n.** opens in th
1a090 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e multi-thread [
1a0a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1a0b0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73  as long as the s
1a0c0 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20  ingle-thread.** 
1a0d0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65  mode has not bee
1a0e0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  n set at compile
1a0f0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1a100 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ime.  ^If the.**
1a110 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1a120 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  LLMUTEX] flag is
1a130 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61   set then the da
1a140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a150 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68  n opens.** in th
1a160 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
1a170 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e  reading mode] un
1a180 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65  less single-thre
1a190 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f  ad was.** previo
1a1a0 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74  usly selected at
1a1b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
1a1c0 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20   start-time..** 
1a1d0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
1a1e0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66  N_SHAREDCACHE] f
1a1f0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1a200 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a210 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67  on to be.** elig
1a220 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61  ible to use [sha
1a230 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c  red cache mode],
1a240 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1a250 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
1a260 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73  ared.** cache is
1a270 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b   enabled using [
1a280 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
1a290 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20  hared_cache()]. 
1a2a0 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45   ^The.** [SQLITE
1a2b0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1a2c0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
1a2d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a2e0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a  nection to not.*
1a2f0 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e  * participate in
1a300 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1a310 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20  ode] even if it 
1a320 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
1a330 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1a340 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
1a350 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1a360 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
1a370 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
1a380 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
1a390 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1a3a0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
1a3b0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1a3c0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1a3d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a3e0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1a3f0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1a400 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1a410 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1a420 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1a430 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1a440 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1a450 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1a460 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1a470 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1a480 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1a490 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1a4a0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1a4b0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1a4c0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1a4d0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1a4e0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1a4f0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1a500 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1a510 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
1a520 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1a530 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1a540 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1a550 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1a560 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1a570 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
1a580 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1a590 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1a5a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1a5b0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1a5c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1a5d0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1a5e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  sed..**.** ^The 
1a5f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1a600 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1a610 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1a620 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1a630 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1a640 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1a650 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1a660 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1a670 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1a680 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a690 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
1a6a0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1a6b0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1a6c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1a6d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1a6e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1a6f0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1a700 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
1a710 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
1a720 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
1a730 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
1a740 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
1a750 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
1a760 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1a770 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
1a780 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
1a790 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
1a7a0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
1a7b0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
1a7c0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
1a7d0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
1a7e0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
1a7f0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
1a800 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
1a810 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
1a820 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1a830 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1a840 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  2()..*/.int sqli
1a850 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1a860 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1a870 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1a880 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1a890 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1a8a0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1a8b0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1a8c0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1a8d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1a8e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1a8f0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1a900 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1a910 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1a920 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1a930 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1a940 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1a950 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1a960 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1a970 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1a980 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1a990 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1a9a0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1a9b0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1a9c0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1a9d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1a9e0 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1a9f0 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1aa00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1aa10 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1aa20 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1aa30 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1aa40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1aa50 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1aa60 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
1aa70 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1aa80 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1aa90 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1aaa0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1aab0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1aac0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1aad0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1aae0 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1aaf0 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1ab00 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1ab10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ab20 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1ab30 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1ab40 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1ab50 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1ab60 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1ab70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1ab80 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1ab90 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1aba0 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
1abb0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
1abc0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
1abd0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
1abe0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1abf0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
1ac00 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
1ac10 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
1ac20 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
1ac30 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
1ac40 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
1ac50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ac60 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
1ac70 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1ac80 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1ac90 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
1aca0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
1acb0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
1acc0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1acd0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1ace0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
1acf0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
1ad00 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
1ad10 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
1ad20 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
1ad30 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
1ad40 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
1ad50 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
1ad60 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
1ad70 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
1ad80 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
1ad90 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
1ada0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
1adb0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
1adc0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
1add0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
1ade0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
1adf0 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
1ae00 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
1ae10 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
1ae20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
1ae30 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
1ae40 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
1ae50 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
1ae60 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
1ae70 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
1ae80 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
1ae90 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
1aea0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
1aeb0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
1aec0 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
1aed0 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
1aee0 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
1aef0 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
1af00 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
1af10 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
1af20 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
1af30 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
1af40 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
1af50 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
1af60 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
1af70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1af80 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
1af90 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
1afa0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
1afb0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
1afc0 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
1afd0 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
1afe0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
1aff0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
1b000 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
1b010 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
1b020 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
1b030 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
1b040 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
1b050 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
1b060 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
1b070 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
1b080 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
1b090 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
1b0a0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
1b0b0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
1b0c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
1b0d0 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
1b0e0 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
1b0f0 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
1b100 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
1b110 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b120 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
1b130 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
1b140 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1b150 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
1b160 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1b170 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
1b180 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
1b190 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
1b1a0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
1b1b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b1c0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
1b1d0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
1b1e0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
1b1f0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
1b200 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
1b210 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
1b220 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
1b230 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
1b240 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
1b250 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
1b260 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
1b270 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
1b280 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
1b290 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
1b2a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
1b2b0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
1b2c0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
1b2d0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
1b2e0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
1b2f0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
1b300 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1b310 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
1b320 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
1b330 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
1b340 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
1b350 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
1b360 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
1b370 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
1b380 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
1b390 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
1b3a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
1b3b0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
1b3c0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
1b3d0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
1b3e0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1b3f0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
1b400 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
1b410 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
1b420 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b430 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
1b440 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
1b450 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
1b460 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
1b470 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
1b480 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
1b490 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1b4a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
1b4b0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
1b4c0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
1b4d0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
1b4e0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
1b4f0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1b500 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1b510 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
1b520 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
1b530 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
1b540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1b550 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
1b560 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
1b570 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
1b580 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
1b590 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1b5a0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
1b5b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
1b5c0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
1b5d0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1b5e0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
1b5f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b600 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
1b610 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
1b620 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
1b630 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1b640 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
1b650 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
1b660 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
1b670 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
1b680 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
1b690 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
1b6a0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
1b6b0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
1b6c0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
1b6d0 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66  onstruct.  The f
1b6e0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1b6f0 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e  the old limit.)^
1b700 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
1b710 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
1b720 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
1b730 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
1b740 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
1b750 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  the limit catego
1b760 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d  ry of SQLITE_LIM
1b770 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20  IT_XYZ there is 
1b780 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
1b790 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1b7a0 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f  ].** set by a co
1b7b0 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65  mpile-time C pre
1b7c0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1b7d0 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74  named .** [limit
1b7e0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58  s | SQLITE_MAX_X
1b7f0 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  YZ]..** (The "_L
1b800 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
1b810 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
1b820 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
1b830 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
1b840 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1b850 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1b860 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1b870 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1b880 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1b890 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
1b8a0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
1b8b0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1b8c0 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1b8d0 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1b8e0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1b8f0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1b900 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1b910 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1b920 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1b930 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1b940 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1b950 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1b960 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1b970 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
1b980 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
1b990 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
1b9a0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1b9b0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1b9c0 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1b9d0 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1b9e0 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1b9f0 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1ba00 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1ba10 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1ba20 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1ba30 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1ba40 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1ba50 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1ba60 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1ba70 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1ba80 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1ba90 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1baa0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1bab0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1bac0 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1bad0 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1bae0 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1baf0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1bb00 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1bb10 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1bb20 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1bb30 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1bb40 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1bb50 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1bb60 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1bb70 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1bb80 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1bb90 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1bba0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1bbb0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
1bbc0 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
1bbd0 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
1bbe0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
1bbf0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
1bc00 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
1bc10 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1bc20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
1bc30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bc40 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
1bc50 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
1bc60 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
1bc70 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
1bc80 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
1bc90 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
1bca0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
1bcb0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
1bcc0 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
1bcd0 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
1bce0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
1bcf0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1bd00 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
1bd10 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
1bd20 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
1bd30 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
1bd40 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
1bd50 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1bd60 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
1bd70 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
1bd80 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
1bd90 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1bda0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1bdb0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1bdc0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
1bdd0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
1bde0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
1bdf0 6c 65 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a  le row.<dd>)^.**
1be00 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1be10 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
1be20 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1be30 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1be40 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
1be50 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
1be60 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1be70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1be80 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
1be90 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1bea0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1beb0 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
1bec0 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
1bed0 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
1bee0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
1bef0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
1bf00 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
1bf10 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
1bf20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
1bf30 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
1bf40 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
1bf50 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1bf60 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
1bf70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1bf80 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
1bf90 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
1bfa0 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
1bfb0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1bfc0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1bfd0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
1bfe0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1bff0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c000 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
1c010 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
1c020 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
1c030 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1c040 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
1c050 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c060 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c070 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
1c080 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
1c090 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
1c0a0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1c0b0 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
1c0c0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
1c0d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c0e0 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
1c0f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c100 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1c110 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
1c120 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
1c130 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1c140 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1c150 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
1c160 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c170 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
1c180 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
1c190 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
1c1a0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1c1b0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1c1c0 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1c1d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c1e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1c1f0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1c200 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1c210 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1c220 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1c230 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c240 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1c250 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1c260 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1c270 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
1c280 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
1c290 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
1c2a0 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
1c2b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c2c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1c2d0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
1c2e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c2f0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
1c300 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
1c310 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
1c320 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1c330 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1c340 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1c350 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1c360 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1c370 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1c380 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1c390 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1c3a0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1c3b0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1c3c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1c3d0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1c3e0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1c3f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c400 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1c410 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1c420 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c430 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1c440 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1c450 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c460 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1c470 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1c480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c490 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1c4a0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1c4b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c4c0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1c4d0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1c4e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c4f0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1c500 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1c510 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c520 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1c530 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
1c540 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
1c550 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1c560 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
1c570 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1c580 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1c590 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
1c5a0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
1c5b0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
1c5c0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
1c5d0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
1c5e0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
1c5f0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
1c600 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
1c610 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
1c620 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
1c630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c640 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1c650 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
1c660 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1c670 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1c680 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c690 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1c6a0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
1c6b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c6c0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
1c6d0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
1c6e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
1c6f0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
1c700 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
1c710 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
1c720 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
1c730 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1c740 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
1c750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1c760 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1c770 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
1c780 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
1c790 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
1c7a0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
1c7b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1c7c0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
1c7d0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
1c7e0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1c7f0 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
1c800 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
1c810 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1c820 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
1c830 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
1c840 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1c850 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
1c860 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1c870 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
1c880 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1c890 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
1c8a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1c8b0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
1c8c0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
1c8d0 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
1c8e0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
1c8f0 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
1c900 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
1c910 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
1c920 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
1c930 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
1c940 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
1c950 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
1c960 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
1c970 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
1c980 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
1c990 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
1c9a0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
1c9b0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
1c9c0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
1c9d0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
1c9e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1c9f0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1ca00 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
1ca10 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
1ca20 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
1ca30 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
1ca40 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
1ca50 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
1ca60 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1ca70 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
1ca80 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1ca90 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
1caa0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1cab0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
1cac0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
1cad0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
1cae0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
1caf0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
1cb00 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
1cb10 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
1cb20 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
1cb30 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
1cb40 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
1cb50 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
1cb60 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1cb70 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
1cb80 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1cb90 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
1cba0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
1cbb0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
1cbc0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
1cbd0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
1cbe0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
1cbf0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
1cc00 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
1cc10 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
1cc20 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
1cc30 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
1cc40 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
1cc50 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1cc60 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1cc70 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1cc80 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1cc90 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1cca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1ccb0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1ccc0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1ccd0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
1cce0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
1ccf0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
1cd00 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1cd10 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
1cd20 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1cd30 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
1cd40 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1cd50 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1cd60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1cd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1cd80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1cd90 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1cda0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1cdb0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1cdc0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1cdd0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1cde0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1cdf0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1ce00 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1ce10 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1ce20 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1ce30 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
1ce40 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1ce50 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1ce60 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1ce70 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1ce80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1ce90 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1cea0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
1ceb0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
1cec0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
1ced0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
1cee0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
1cef0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
1cf00 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
1cf10 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
1cf20 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
1cf30 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1cf40 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
1cf50 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
1cf60 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
1cf70 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
1cf80 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
1cf90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cfa0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
1cfb0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
1cfc0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
1cfd0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
1cfe0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49  un it again.  ^I
1cff0 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1d000 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1d010 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1d020 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1d030 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1d040 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d050 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1d060 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1d070 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1d080 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1d090 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1d0a0 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1d0b0 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1d0c0 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1d0d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d0e0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1d0f0 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1d100 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1d110 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1d120 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1d130 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1d140 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1d150 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1d160 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1d170 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
1d180 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1d190 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
1d1a0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
1d1b0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1d1c0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1d1d0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
1d1e0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1d1f0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1d200 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
1d210 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1d220 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1d230 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1d240 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1d250 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1d260 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1d270 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
1d280 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
1d290 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
1d2a0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
1d2b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
1d2c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
1d2d0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
1d2e0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
1d2f0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
1d300 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
1d310 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1d320 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
1d330 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
1d340 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1d350 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
1d360 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1d370 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ^If the value of
1d380 20 61 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20   a [parameter | 
1d390 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
1d3a0 69 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  in the WHERE cla
1d3b0 75 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61  use might.** cha
1d3c0 6e 67 65 20 74 68 65 20 71 75 65 72 79 20 70 6c  nge the query pl
1d3d0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
1d3e0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61  nt, then the sta
1d3f0 74 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a  tement may be.**
1d400 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1d410 65 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66  ecompiled (as if
1d420 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
1d430 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29  a schema change)
1d440 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a   on the first .*
1d450 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1d460 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
1d470 67 20 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20  g any change to 
1d480 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
1d490 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
1d4a0 64 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70  dings] of the [p
1d4b0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c  arameter]. .** <
1d4c0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  /li>.** </ol>.*/
1d4d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1d4e0 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
1d4f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1d500 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1d510 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1d520 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1d530 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1d540 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1d550 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1d560 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1d570 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1d580 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1d590 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1d5a0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1d5b0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1d5c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1d5d0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1d5e0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1d5f0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1d600 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1d610 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1d620 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
1d630 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1d640 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1d650 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1d660 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1d670 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1d680 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1d690 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1d6a0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1d6b0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1d6c0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1d6d0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1d6e0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1d6f0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1d700 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1d710 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1d720 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1d730 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1d740 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1d750 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1d760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1d770 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1d780 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
1d790 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
1d7a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
1d7b0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
1d7c0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
1d7d0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
1d7e0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
1d7f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
1d800 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
1d810 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
1d820 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
1d830 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
1d840 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
1d850 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
1d860 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
1d870 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
1d880 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
1d890 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
1d8a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1d8b0 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
1d8c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d8d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1d8e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1d8f0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
1d900 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1d910 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
1d920 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1d930 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1d940 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1d950 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1d960 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1d970 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1d980 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1d990 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1d9a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
1d9b0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1d9c0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1d9d0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1d9e0 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
1d9f0 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
1da00 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
1da10 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  QL.**.** ^This i
1da20 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
1da30 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65  used to retrieve
1da40 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66   a saved copy of
1da50 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a   the original.**
1da60 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74   SQL text used t
1da70 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70  o create a [prep
1da80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1da90 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  if that statemen
1daa0 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  t was.** compile
1dab0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1dac0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1dad0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
1dae0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1daf0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
1db00 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
1db10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1db20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1db30 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
1db40 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
1db50 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1db60 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
1db70 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
1db80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1db90 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
1dba0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
1dbb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1dbc0 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
1dbd0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
1dbe0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
1dbf0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
1dc00 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
1dc10 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
1dc20 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
1dc30 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
1dc40 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
1dc50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1dc60 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
1dc70 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
1dc80 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
1dc90 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
1dca0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
1dcb0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
1dcc0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
1dcd0 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
1dce0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
1dcf0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
1dd00 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
1dd10 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1dd20 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
1dd30 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
1dd40 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
1dd50 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
1dd60 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
1dd70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1dd80 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
1dd90 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
1dda0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
1ddb0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
1ddc0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
1ddd0 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
1dde0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1ddf0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
1de00 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
1de10 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
1de20 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
1de30 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
1de40 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
1de50 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20  ld.  A internal 
1de60 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
1de70 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a  r a protected.**
1de80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1de90 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74  bject but no mut
1dea0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
1deb0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  n unprotected.**
1dec0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ded0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74  bject.  If SQLit
1dee0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f  e is compiled to
1def0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61   be single-threa
1df00 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51  ded.** (with [SQ
1df10 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1df20 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c  0] and with [sql
1df30 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1df40 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a  )] returning 0).
1df50 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20  ** or if SQLite 
1df60 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66  is run in one of
1df70 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d   reduced mutex m
1df80 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  odes .** [SQLITE
1df90 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1dfa0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1dfb0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1dfc0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  EAD].** then the
1dfd0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63  re is no distinc
1dfe0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
1dff0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
1e000 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
1e010 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1e020 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20  and they can be 
1e030 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65  used interchange
1e040 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a  ably.  However,.
1e050 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63  ** for maximum c
1e060 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20  ode portability 
1e070 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
1e080 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
1e090 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b  ons.** still mak
1e0a0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
1e0b0 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65  n between betwee
1e0c0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1e0d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1e0e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e0f0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
1e100 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
1e110 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
1e120 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e130 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
1e140 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
1e150 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
1e160 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1e170 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
1e180 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1e190 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
1e1a0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
1e1b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e1c0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
1e1d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
1e1e0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
1e1f0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
1e200 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e210 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
1e220 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
1e230 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
1e240 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
1e250 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
1e260 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
1e270 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
1e280 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
1e290 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
1e2a0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
1e2b0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1e2c0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
1e2d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1e2e0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1e2f0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
1e300 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
1e310 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
1e320 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
1e330 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
1e340 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
1e350 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
1e360 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
1e370 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
1e380 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1e390 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
1e3a0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
1e3b0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
1e3c0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
1e3d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
1e3e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1e3f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
1e400 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1e410 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1e420 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
1e430 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
1e440 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
1e450 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
1e460 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1e470 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
1e480 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
1e490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
1e4a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
1e4b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
1e4c0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
1e4d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
1e4e0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
1e4f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1e500 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
1e510 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1e520 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
1e530 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1e540 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
1e550 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
1e560 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
1e570 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
1e580 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
1e590 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1e5a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
1e5b0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
1e5c0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1e5d0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
1e5e0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
1e5f0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
1e600 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
1e610 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
1e620 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
1e630 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
1e640 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
1e650 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1e660 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
1e670 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
1e680 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
1e690 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
1e6a0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
1e6b0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
1e6c0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
1e6d0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
1e6e0 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
1e6f0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
1e700 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
1e710 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
1e720 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
1e730 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
1e740 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
1e750 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
1e760 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
1e770 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
1e780 65 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e 29  eric identifer.)
1e790 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
1e7a0 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
1e7b0 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
1e7c0 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
1e7d0 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
1e7e0 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
1e7f0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
1e800 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1e810 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
1e820 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
1e830 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1e840 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1e850 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1e860 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
1e870 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
1e880 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1e890 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
1e8a0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
1e8b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e8c0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
1e8d0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
1e8e0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1e8f0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
1e900 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
1e910 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
1e920 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
1e930 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
1e940 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
1e950 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
1e960 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
1e970 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
1e980 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
1e990 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
1e9a0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
1e9b0 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
1e9c0 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
1e9d0 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
1e9e0 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
1e9f0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
1ea00 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
1ea10 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
1ea20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ea30 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1ea40 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
1ea50 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
1ea60 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1ea70 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1ea80 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1ea90 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
1eaa0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
1eab0 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
1eac0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
1ead0 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
1eae0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1eaf0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
1eb00 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
1eb10 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
1eb20 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
1eb30 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
1eb40 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1eb50 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
1eb60 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
1eb70 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
1eb80 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
1eb90 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1eba0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1ebb0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
1ebc0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
1ebd0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1ebe0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
1ebf0 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
1ec00 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
1ec10 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
1ec20 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
1ec30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
1ec40 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20  s negative, the 
1ec50 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
1ec60 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
1ec70 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
1ec80 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1ec90 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1eca0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
1ecb0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1ecc0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
1ecd0 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  , sqlite3_bind_t
1ece0 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71  ext(), and.** sq
1ecf0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
1ed00 36 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63  6() is a destruc
1ed10 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
1ed20 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1ed30 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
1ed40 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
1ed50 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
1ed60 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
1ed70 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
1ed80 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
1ed90 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
1eda0 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
1edb0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
1edc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
1edd0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
1ede0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
1edf0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
1ee00 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
1ee10 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
1ee20 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
1ee30 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
1ee40 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
1ee50 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
1ee60 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
1ee70 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
1ee80 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
1ee90 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
1eea0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
1eeb0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
1eec0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1eed0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
1eee0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
1eef0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
1ef00 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
1ef10 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
1ef20 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
1ef30 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
1ef40 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
1ef50 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
1ef60 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
1ef70 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
1ef80 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
1ef90 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
1efa0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
1efb0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
1efc0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
1efd0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
1efe0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
1eff0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
1f000 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
1f010 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
1f020 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
1f030 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
1f040 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
1f050 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
1f060 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
1f070 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
1f080 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
1f090 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
1f0a0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1f0b0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
1f0c0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f0d0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
1f0e0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
1f0f0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
1f100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
1f110 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
1f120 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
1f130 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
1f140 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
1f150 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
1f160 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
1f170 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
1f180 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
1f190 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
1f1a0 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
1f1b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1f1c0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
1f1d0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
1f1e0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
1f1f0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
1f200 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
1f210 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
1f220 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
1f230 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
1f240 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
1f250 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
1f260 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
1f270 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
1f280 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1f290 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
1f2a0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
1f2b0 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
1f2c0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
1f2d0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
1f2e0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
1f2f0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
1f300 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
1f310 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
1f320 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
1f330 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
1f340 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1f350 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
1f360 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1f370 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f380 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1f390 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1f3a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1f3b0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
1f3c0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1f3d0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
1f3e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1f3f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
1f400 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1f410 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
1f420 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
1f430 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f440 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
1f450 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
1f460 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
1f470 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
1f480 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
1f490 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1f4a0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
1f4b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
1f4c0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
1f4d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
1f4e0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
1f4f0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
1f500 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
1f510 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1f520 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
1f530 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
1f540 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1f550 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1f560 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1f570 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
1f580 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
1f590 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1f5a0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
1f5b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f5c0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
1f5d0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
1f5e0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
1f5f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
1f600 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
1f610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f620 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
1f630 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
1f640 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
1f650 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
1f660 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
1f670 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
1f680 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
1f690 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
1f6a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
1f6b0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
1f6c0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
1f6d0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
1f6e0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
1f6f0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
1f700 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
1f710 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
1f720 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1f730 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
1f740 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
1f750 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
1f760 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
1f770 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
1f780 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
1f790 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
1f7a0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
1f7b0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
1f7c0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
1f7d0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
1f7e0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
1f7f0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1f800 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
1f810 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
1f820 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
1f830 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
1f840 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
1f850 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
1f860 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1f870 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1f880 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1f890 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1f8a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f8b0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
1f8c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1f8d0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1f8e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f8f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f900 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
1f910 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
1f920 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
1f930 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
1f940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f950 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f960 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
1f970 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
1f980 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1f990 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
1f9a0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
1f9b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1f9c0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
1f9d0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
1f9e0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
1f9f0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1fa00 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
1fa10 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
1fa20 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
1fa30 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1fa40 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1fa50 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
1fa60 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
1fa70 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
1fa80 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
1fa90 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
1faa0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
1fab0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
1fac0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
1fad0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
1fae0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
1faf0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
1fb00 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
1fb10 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
1fb20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
1fb30 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
1fb40 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
1fb50 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
1fb60 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1fb70 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
1fb80 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
1fb90 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
1fba0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
1fbb0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
1fbc0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
1fbd0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
1fbe0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
1fbf0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1fc00 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
1fc10 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
1fc20 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
1fc30 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
1fc40 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
1fc50 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
1fc60 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
1fc70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
1fc80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fc90 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1fca0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1fcb0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1fcc0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1fcd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1fce0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1fcf0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1fd00 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1fd10 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
1fd20 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1fd30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1fd40 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1fd50 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
1fd60 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
1fd70 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
1fd80 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
1fd90 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
1fda0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
1fdb0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
1fdc0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
1fdd0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
1fde0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
1fdf0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
1fe00 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
1fe10 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
1fe20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1fe30 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1fe40 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
1fe50 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
1fe60 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
1fe70 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
1fe80 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
1fe90 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
1fea0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
1feb0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
1fec0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
1fed0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
1fee0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
1fef0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1ff00 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1ff10 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
1ff20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1ff30 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
1ff40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1ff50 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
1ff60 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
1ff70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1ff80 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
1ff90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
1ffa0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1ffb0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
1ffc0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
1ffd0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
1ffe0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
1fff0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
20000 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
20010 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
20020 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
20030 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
20040 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
20050 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
20060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
20070 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
20080 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
20090 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
200a0 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
200b0 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
200c0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
200d0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
200e0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
200f0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
20100 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
20110 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
20120 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
20130 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
20140 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
20150 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
20160 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20170 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
20180 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
20190 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
201a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
201b0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
201c0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
201d0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
201e0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
201f0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
20200 54 45 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  TE])..*/.int sql
20210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
20220 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
20230 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
20240 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
20250 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
20260 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
20270 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
20280 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
20290 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
202a0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
202b0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
202c0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
202d0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
202e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
202f0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
20300 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
20310 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
20320 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
20330 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
20340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20350 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
20360 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
20370 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
20380 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
20390 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
203a0 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
203b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
203c0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
203d0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
203e0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
203f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20400 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
20410 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
20420 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
20430 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
20440 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
20450 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
20460 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
20470 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
20480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
20490 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
204a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
204b0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
204c0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
204d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
204e0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
204f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20500 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
20510 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
20520 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
20530 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
20540 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
20550 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
20560 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
20570 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
20580 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
20590 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
205a0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
205b0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
205c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
205d0 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
205e0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
205f0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
20600 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
20610 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
20620 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
20630 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
20640 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
20650 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
20660 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
20670 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
20680 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
20690 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
206a0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
206b0 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
206c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
206d0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
206e0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
206f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
20700 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
20710 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20720 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
20730 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
20740 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
20750 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
20760 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
20770 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
20780 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
20790 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
207a0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
207b0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
207c0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
207d0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
207e0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
207f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
20800 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
20810 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
20820 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
20830 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
20840 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
20850 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
20860 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
20870 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
20880 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
20890 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
208a0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
208b0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
208c0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
208d0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
208e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
208f0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
20900 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
20910 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
20920 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
20930 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
20940 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
20950 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
20960 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
20970 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
20980 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
20990 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
209a0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
209b0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
209c0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
209d0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
209e0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
209f0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
20a00 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
20a10 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
20a20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
20a30 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
20a40 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
20a50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20a60 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
20a70 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
20a80 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
20a90 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
20aa0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
20ab0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
20ac0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
20ad0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
20ae0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
20af0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
20b00 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
20b10 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
20b20 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
20b30 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
20b40 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
20b50 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
20b60 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
20b70 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
20b80 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
20b90 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
20ba0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
20bb0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
20bc0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
20bd0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
20be0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
20bf0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
20c00 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
20c10 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
20c20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
20c30 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
20c40 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
20c50 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
20c60 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
20c70 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
20c80 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
20c90 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
20ca0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
20cb0 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
20cc0 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
20cd0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
20ce0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
20cf0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
20d00 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
20d10 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
20d20 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
20d30 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
20d40 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
20d50 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
20d60 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
20d70 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
20d80 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
20d90 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
20da0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
20db0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
20dc0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
20dd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
20de0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
20df0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20e00 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
20e10 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
20e20 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
20e30 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
20e40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
20e50 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
20e60 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
20e70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
20e80 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
20e90 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
20ea0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
20eb0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
20ec0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20ed0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
20ee0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
20ef0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
20f00 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
20f10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
20f20 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
20f30 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
20f40 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
20f50 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
20f60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
20f70 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
20f80 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
20f90 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
20fa0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
20fb0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
20fc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
20fd0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
20fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
20ff0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
21000 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
21010 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
21020 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
21030 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
21040 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
21050 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
21060 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
21070 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21080 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
21090 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
210a0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
210b0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
210c0 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
210d0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
210e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
210f0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
21100 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
21110 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
21120 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
21130 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
21140 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
21150 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
21160 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
21170 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
21180 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
21190 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
211a0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
211b0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
211c0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
211d0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
211e0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
211f0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
21200 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
21210 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
21220 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
21230 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
21240 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
21250 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
21260 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
21270 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
21280 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
21290 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
212a0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
212b0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
212c0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
212d0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
212e0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
212f0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
21300 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
21310 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
21320 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
21330 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
21340 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
21350 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
21360 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
21370 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
21380 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
21390 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
213a0 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
213b0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
213c0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
213d0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
213e0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
213f0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
21400 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
21410 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
21420 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
21430 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
21440 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
21450 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
21460 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
21470 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
21480 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
21490 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
214a0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
214b0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
214c0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
214d0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
214e0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
214f0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
21500 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
21510 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
21520 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
21530 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
21540 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
21550 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
21560 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
21570 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
21580 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
21590 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
215a0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
215b0 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
215c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
215d0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
215e0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
215f0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
21600 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21610 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
21620 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
21630 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
21640 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
21650 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
21660 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
21670 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
21680 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
21690 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
216a0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
216b0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
216c0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
216d0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
216e0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
216f0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
21700 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
21710 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
21720 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
21730 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
21740 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
21750 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
21760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21770 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
21780 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21790 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
217a0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
217b0 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
217c0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
217d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
217e0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
217f0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
21800 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
21810 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
21820 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
21830 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
21840 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
21850 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
21860 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
21870 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
21880 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
21890 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
218a0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
218b0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
218c0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
218d0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
218e0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
218f0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
21900 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
21910 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
21920 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
21930 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
21940 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21950 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
21960 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
21970 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
21980 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
21990 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
219a0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
219b0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
219c0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
219d0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
219e0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
219f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
21a00 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
21a10 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
21a20 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
21a30 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
21a40 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
21a50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
21a60 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
21a70 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
21a80 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
21a90 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63  thin a.** explic
21aa0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
21ab0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
21ac0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
21ad0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
21ae0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
21af0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
21b00 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
21b10 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
21b20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
21b30 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
21b40 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
21b50 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
21b60 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
21b70 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
21b80 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
21b90 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
21ba0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21bb0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
21bc0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
21bd0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
21be0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
21bf0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
21c00 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
21c10 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
21c20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
21c30 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
21c40 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
21c50 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
21c60 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
21c70 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
21c80 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
21c90 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
21ca0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
21cb0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
21cc0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
21cd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
21ce0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
21cf0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
21d00 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
21d10 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
21d20 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
21d30 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
21d40 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
21d50 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
21d60 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
21d70 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
21d80 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
21d90 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
21da0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
21db0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
21dc0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
21dd0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
21de0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
21df0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
21e00 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
21e10 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
21e20 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
21e30 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
21e40 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
21e50 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
21e60 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
21e70 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
21e80 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
21e90 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
21ea0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
21eb0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
21ec0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
21ed0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
21ee0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
21ef0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
21f00 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
21f10 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
21f20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
21f30 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
21f40 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
21f50 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
21f60 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
21f70 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
21f80 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
21f90 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
21fa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21fb0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
21fc0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
21fd0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
21fe0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
21ff0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
22000 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
22010 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
22020 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
22030 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
22040 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
22050 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
22060 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22070 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
22080 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
22090 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
220a0 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
220b0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
220c0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
220d0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
220e0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
220f0 33 2e 31 2c 20 69 74 20 77 61 73 20 72 65 71 75  3.1, it was requ
22100 69 72 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71  ired.** after sq
22110 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
22120 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f  urned anything o
22130 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
22140 45 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b  E_ROW] that.** [
22150 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22160 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
22170 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  e any subsequent
22180 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a   invocation of.*
22190 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
221a0 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e  .  Failure to in
221b0 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  voke [sqlite3_re
221c0 73 65 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77  set()] in this w
221d0 61 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75  ay would.** resu
221e0 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
221f0 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
22200 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65  from sqlite3_ste
22210 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a  p().  But after.
22220 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  ** version 3.6.2
22230 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
22240 70 28 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e  p() began callin
22250 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
22260 28 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  ()] .** automati
22270 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
22280 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
22290 72 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  r than returning
222a0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
222b0 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  .  .**.** <b>Goo
222c0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
222d0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
222e0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
222f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
22300 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
22310 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
22320 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
22330 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
22340 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
22350 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
22360 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
22370 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
22380 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
22390 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
223a0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
223b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
223c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
223d0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
223e0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
223f0 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
22400 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
22410 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
22420 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
22430 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
22440 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
22450 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
22460 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
22470 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
22480 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
22490 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
224a0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74  nts.** using eit
224b0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
224c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
224d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
224e0 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a  _v2()] instead.*
224f0 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20  * of the legacy 
22500 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22510 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
22520 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e  _prepare16()] in
22530 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65  terfaces,.** the
22540 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  n the more speci
22550 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
22560 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64  ] are returned d
22570 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71  irectly.** by sq
22580 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54  lite3_step().  T
22590 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76  he use of the "v
225a0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
225b0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a  recommended..*/.
225c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
225d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
225e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
225f0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
22600 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
22610 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  set.**.** ^The s
22620 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
22630 74 28 50 29 20 74 68 65 20 6e 75 6d 62 65 72 20  t(P) the number 
22640 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
22650 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
22660 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
22670 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
22680 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22690 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
226a0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
226b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
226c0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
226d0 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
226e0 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
226f0 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
22700 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
22710 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
22720 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
22730 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
22740 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
22750 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
22760 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
22770 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
22780 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
22790 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
227a0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
227b0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
227c0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
227d0 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
227e0 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
227f0 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
22800 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
22810 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
22820 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
22830 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
22840 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
22850 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
22860 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
22870 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
22880 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
22890 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
228a0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
228b0 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
228c0 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
228d0 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
228e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
228f0 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
22900 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
22910 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
22920 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
22930 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
22940 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
22950 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
22960 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
22970 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
22980 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
22990 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
229a0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
229b0 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
229c0 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
229d0 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
229e0 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
229f0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
22a00 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
22a10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
22a20 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
22a30 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  et" interface..*
22a40 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
22a50 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
22a60 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
22a70 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
22a80 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
22a90 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
22aa0 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
22ab0 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
22ac0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
22ad0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
22ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
22af0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
22b00 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
22b10 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
22b20 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
22b30 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
22b40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
22b50 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
22b60 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
22b70 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
22b80 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
22b90 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
22ba0 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
22bb0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
22bc0 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
22bd0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
22be0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
22bf0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
22c00 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
22c10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22c20 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
22c30 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
22c40 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
22c50 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
22c60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
22c70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
22c80 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
22c90 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
22ca0 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
22cb0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
22cc0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
22cd0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
22ce0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
22cf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
22d00 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
22d10 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
22d20 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
22d30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22d40 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
22d50 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
22d60 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
22d70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
22d80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22d90 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
22da0 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
22db0 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
22dc0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
22dd0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
22de0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
22df0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
22e00 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
22e10 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
22e20 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
22e30 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
22e40 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
22e50 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
22e60 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
22e70 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
22e80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
22e90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22ea0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
22eb0 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
22ec0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
22ed0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
22ee0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
22ef0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
22f00 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
22f10 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
22f20 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
22f30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22f40 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
22f50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
22f60 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
22f70 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
22f80 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
22f90 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
22fa0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
22fb0 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
22fc0 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
22fd0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
22fe0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
22ff0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
23000 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
23010 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
23020 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
23030 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
23040 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
23050 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
23060 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
23070 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
23080 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
23090 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
230a0 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
230b0 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
230c0 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
230d0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
230e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
230f0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
23100 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
23110 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23120 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
23130 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
23140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
23150 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
23160 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
23170 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23180 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
23190 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
231a0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
231b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
231c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
231d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
231e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
231f0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
23200 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
23210 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
23220 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
23230 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23240 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
23250 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
23260 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
23270 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
23280 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
23290 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
232a0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
232b0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
232c0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
232d0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
232e0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
232f0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
23300 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
23310 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
23320 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
23330 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
23340 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
23350 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
23360 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
23370 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20  o terminator at 
23380 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
23390 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
233a0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
233b0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
233c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
233d0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
233e0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
233f0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
23400 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
23410 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
23420 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23430 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
23440 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
23450 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
23460 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
23470 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  ys zero terminat
23480 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
23490 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
234a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
234b0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
234c0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
234d0 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70  n arbitrary.** p
234e0 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79  ointer, possibly
234f0 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   even a NULL poi
23500 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
23510 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23520 62 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e  bytes16() routin
23530 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
23540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23550 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65  ytes().** but le
23560 61 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20  aves the result 
23570 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  in UTF-16 in nat
23580 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
23590 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e  nstead of UTF-8.
235a0 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65  .** ^The zero te
235b0 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20  rminator is not 
235c0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73  included in this
235d0 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54   count..**.** ^T
235e0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
235f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
23600 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
23610 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
23620 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23630 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
23640 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
23650 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23660 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
23670 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
23680 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
23690 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
236a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
236b0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
236c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
236d0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
236e0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
236f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
23700 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
23710 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
23720 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
23730 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
23740 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
23750 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
23760 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
23770 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
23780 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
23790 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
237a0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
237b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
237c0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
237d0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
237e0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
237f0 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
23800 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
23810 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
23820 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
23830 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
23840 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
23850 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
23860 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
23870 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
23880 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
23890 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
238a0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
238b0 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
238c0 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
238d0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
238e0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
238f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
23900 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
23910 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
23920 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
23930 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
23940 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
23950 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
23960 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
23970 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
23980 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
23990 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
239a0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
239b0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
239c0 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
239d0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
239e0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
239f0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
23a00 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
23a10 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
23a20 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
23a30 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
23a40 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
23a50 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
23a60 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
23a70 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
23a80 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
23a90 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
23aa0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
23ab0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
23ac0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
23ad0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
23ae0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
23af0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
23b00 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
23b10 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
23b20 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
23b30 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
23b40 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
23b50 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
23b60 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
23b70 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
23b80 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
23b90 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
23ba0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
23bb0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
23bc0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
23bd0 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
23be0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
23bf0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
23c00 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
23c10 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23c20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
23c30 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
23c40 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
23c50 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
23c60 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
23c70 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
23c80 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
23c90 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
23ca0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
23cb0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
23cc0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
23cd0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
23ce0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
23cf0 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
23d00 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
23d10 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
23d20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
23d30 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
23d40 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
23d50 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
23d60 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
23d70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
23d80 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
23d90 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
23da0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
23db0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
23dc0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
23dd0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
23de0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
23df0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
23e00 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
23e10 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
23e20 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
23e30 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
23e40 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
23e50 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
23e60 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
23e70 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
23e80 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
23e90 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
23ea0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  ammers..**.** ^N
23eb0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
23ec0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
23ed0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
23ee0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
23ef0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
23f00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
23f10 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
23f20 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
23f30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
23f40 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
23f50 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
23f60 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65  .** ^(Type conve
23f70 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
23f80 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
23f90 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
23fa0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
23fb0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
23fc0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
23fd0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
23fe0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
23ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24000 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
24010 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24020 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
24030 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
24040 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
24050 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
24060 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
24070 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
24080 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
24090 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
240a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
240b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
240c0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
240d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
240e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
240f0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
24100 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
24110 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
24120 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
24130 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
24140 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
24150 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
24160 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
24170 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
24180 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
24190 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
241a0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
241b0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
241c0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
241d0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  ul>)^.**.** ^Con
241e0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
241f0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
24200 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
24210 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
24220 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
24230 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
24240 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
24250 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
24260 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
24270 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
24280 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
24290 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
242a0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
242b0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
242c0 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
242d0 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
242e0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
242f0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
24300 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
24310 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
24320 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
24330 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
24340 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
24350 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66  .**.** ^(The saf
24360 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
24370 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
24380 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
24390 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
243a0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
243b0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
243c0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
243d0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
243e0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
243f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
24400 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
24410 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
24420 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
24430 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
24440 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
24450 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
24460 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24470 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
24480 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
24490 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
244a0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
244b0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
244c0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
244d0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
244e0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
244f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
24500 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
24510 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
24520 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
24530 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
24540 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
24550 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
24560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24570 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
24580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24590 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
245a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
245b0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
245c0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
245d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
245e0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
245f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
24600 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
24610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24620 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
24630 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
24640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24650 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
24660 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24670 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
24680 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
24690 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
246a0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
246b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
246c0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
246d0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
246e0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
246f0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
24700 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
24710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
24720 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
24730 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
24740 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
24750 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
24760 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
24770 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
24780 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
24790 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
247a0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
247b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
247c0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
247d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
247e0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
247f0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
24800 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
24810 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
24820 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
24830 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
24840 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
24850 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
24860 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
24870 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
24880 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
24890 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
248a0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
248b0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
248c0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
248d0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
248e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
248f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
24900 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
24910 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
24920 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
24930 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
24940 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
24950 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24960 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
24970 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
24980 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24990 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
249a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
249b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
249c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
249d0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
249e0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
249f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24a00 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
24a10 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
24a20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24a30 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
24a40 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
24a50 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
24a60 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24a70 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
24a80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
24a90 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
24aa0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
24ab0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
24ac0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
24ad0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
24ae0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24af0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
24b00 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
24b10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24b20 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
24b30 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24b40 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
24b50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24b60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24b70 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
24b80 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
24b90 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
24ba0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
24bb0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
24bc0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
24bd0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24be0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
24bf0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
24c00 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65  s executed succe
24c10 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65  ssfully or not e
24c20 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20  xecuted at all, 
24c30 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  then.** SQLITE_O
24c40 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e  K is returned. ^
24c50 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
24c60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
24c70 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20  iled then an.** 
24c80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
24c90 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
24ca0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
24cb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
24cc0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
24cd0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
24ce0 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
24cf0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
24d00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24d10 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20  ment].  ^If the 
24d20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
24d30 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
24d40 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
24d50 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
24d60 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
24d70 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
24d80 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
24d90 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
24da0 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
24db0 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63  errupt]..** ^Inc
24dc0 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20  omplete updates 
24dd0 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  may be rolled ba
24de0 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69  ck and transacti
24df0 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a  ons canceled,.**
24e00 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
24e10 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
24e20 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72   and the.** [err
24e30 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65  or code] returne
24e40 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54  d will be [SQLIT
24e50 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74  E_ABORT]..*/.int
24e60 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
24e70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
24e80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
24e90 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
24ea0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
24eb0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
24ec0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
24ed0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
24ee0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
24ef0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24f00 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
24f10 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
24f20 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
24f30 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
24f40 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
24f50 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
24f60 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
24f70 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
24f80 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
24f90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
24fa0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
24fb0 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
24fc0 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
24fd0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
24fe0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
24ff0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
25000 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
25010 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
25020 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
25030 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
25040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25050 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
25060 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
25070 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
25080 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
25090 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
250a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
250b0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
250c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
250d0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
250e0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
250f0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
25100 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
25110 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
25120 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
25130 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
25140 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25150 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
25160 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
25170 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
25180 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
25190 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
251a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
251b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
251c0 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
251d0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
251e0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
251f0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
25200 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
25210 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
25220 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
25230 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
25240 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
25250 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
25260 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
25270 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
25280 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25290 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
252a0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
252b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
252c0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
252d0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
252e0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
252f0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
25300 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
25310 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
25320 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
25330 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
25340 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25350 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
25360 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
25370 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25380 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
25390 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28   two functions (
253a0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
253b0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
253c0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
253d0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
253e0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
253f0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
25400 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
25410 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
25420 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
25430 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
25440 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
25450 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
25460 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74  between the.** t
25470 77 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73  wo is that the s
25480 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c  econd parameter,
25490 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
254a0 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69   (scalar) functi
254b0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
254c0 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69  te, is encoded i
254d0 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69  n UTF-8 for sqli
254e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
254f0 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36  ion() and UTF-16
25500 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
25510 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
25520 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  6()..**.** ^The 
25530 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
25540 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
25550 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
25560 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
25570 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
25580 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
25590 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
255a0 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
255b0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
255c0 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
255d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
255e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
255f0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
25600 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
25610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
25620 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  rately..**.** Th
25630 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
25640 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
25650 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
25660 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
25670 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
25680 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
25690 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
256a0 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
256b0 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  es, exclusive of
256c0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72  .** the zero-ter
256d0 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74  minator.  Note t
256e0 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e  hat the name len
256f0 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
25700 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68  bytes, not.** ch
25710 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20  aracters.  ^Any 
25720 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
25730 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
25740 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
25750 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
25760 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
25770 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
25780 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
25790 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
257a0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
257b0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
257c0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
257d0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
257e0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
257f0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
25800 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
25810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
25820 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
25830 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
25840 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
25850 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
25860 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
25870 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
25880 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
25890 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
258a0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
258b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
258c0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
258d0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
258e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
258f0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
25900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
25910 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
25920 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
25930 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
25940 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
25950 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
25960 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
25970 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
25980 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
25990 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
259a0 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
259b0 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
259c0 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
259d0 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
259e0 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
259f0 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
25a00 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
25a10 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
25a20 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
25a30 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e  than another.  ^
25a40 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  An application m
25a50 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  ay.** invoke sql
25a60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
25a70 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  tion() or sqlite
25a80 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25a90 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a  n16() multiple.*
25aa0 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65  * times with the
25ab0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62   same function b
25ac0 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ut with differen
25ad0 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78  t values of eTex
25ae0 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  tRep..** ^When m
25af0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
25b00 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
25b10 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
25b20 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
25b30 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
25b40 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
25b50 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
25b60 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
25b70 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66  onversion..** If
25b80 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61   there is only a
25b90 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e   single implemen
25ba0 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65  tation which doe
25bb0 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20  s not care what 
25bc0 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67  text.** encoding
25bd0 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74   is used, then t
25be0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
25bf0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51  nt should be [SQ
25c00 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ANY]..**.**
25c10 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
25c20 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
25c30 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
25c40 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
25c50 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
25c60 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
25c70 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
25c80 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
25c90 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
25ca0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].)^.**.** The 
25cb0 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20  seventh, eighth 
25cc0 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65  and ninth parame
25cd0 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74  ters, xFunc, xSt
25ce0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61  ep and xFinal, a
25cf0 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  re.** pointers t
25d00 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e  o C-language fun
25d10 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c  ctions that impl
25d20 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
25d30 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
25d40 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61  regate. ^A scala
25d50 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  r SQL function r
25d60 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
25d70 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
25d80 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61   xFunc.** callba
25d90 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f  ck only; NULL po
25da0 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  inters should be
25db0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
25dc0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
25dd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
25de0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
25df0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
25e00 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
25e10 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
25e20 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
25e30 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
25e40 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
25e50 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
25e60 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
25e70 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
25e80 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
25e90 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75  for all three fu
25ea0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73  nction callbacks
25eb0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70  ..**.** ^It is p
25ec0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
25ed0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
25ee0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
25ef0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
25f00 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
25f10 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
25f20 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
25f30 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
25f40 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
25f50 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
25f60 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
25f70 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  s.  ^SQLite will
25f80 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c   use.** the impl
25f90 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20  ementation that 
25fa0 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74  most closely mat
25fb0 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20  ches the way in 
25fc0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c  which the.** SQL
25fd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
25fe0 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  d.  ^A function 
25ff0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
26000 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69  ith a non-negati
26010 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d  ve.** nArg param
26020 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72  eter is a better
26030 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
26040 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
26050 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20  ation with.** a 
26060 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20  negative nArg.  
26070 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
26080 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
26090 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a  text encoding.**
260a0 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74   matches the dat
260b0 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69  abase encoding i
260c0 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61  s a better.** ma
260d0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
260e0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
260f0 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
26100 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e  ent.  .** ^A fun
26110 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
26120 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
26130 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
26140 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
26150 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
26160 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
26170 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
26180 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
26190 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
261a0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
261b0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74  16..**.** ^Built
261c0 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  -in functions ma
261d0 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20  y be overloaded 
261e0 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  by new applicati
261f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
26200 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ions..** ^The fi
26210 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  rst application-
26220 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26230 20 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61   with a given na
26240 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c  me overrides all
26250 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e  .** built-in fun
26260 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61  ctions in the sa
26270 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
26280 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68  nection] with th
26290 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20  e same name..** 
262a0 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c  ^Subsequent appl
262b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
262c0 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65  functions of the
262d0 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20   same name only 
262e0 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69  override .** pri
262f0 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  or application-d
26300 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
26310 20 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61   that are an exa
26320 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65  ct match for the
26330 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  .** number of pa
26340 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65  rameters and pre
26350 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e  ferred encoding.
26360 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
26370 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
26380 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
26390 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
263a0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
263b0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
263c0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
263d0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
263e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
263f0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
26400 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
26410 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
26420 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
26430 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
26440 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
26450 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
26460 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
26470 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
26480 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
26490 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
264a0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
264b0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
264c0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
264d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
264e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
264f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
26500 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
26510 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
26520 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
26530 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
26540 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
26550 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
26560 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
26570 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
26580 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
26590 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
265a0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
265b0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
265c0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
265d0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
265e0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
265f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
26600 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
26610 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26620 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
26630 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
26640 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
26650 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
26660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
26670 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
26680 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
26690 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
266a0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
266b0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
266c0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
266d0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
266e0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
266f0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
26700 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
26710 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
26720 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
26730 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
26740 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
26750 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
26760 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
26770 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
26780 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
26790 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
267a0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
267b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
267c0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
267d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
267e0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
267f0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
26800 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
26810 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
26820 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
26830 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
26840 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
26850 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
26860 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
26870 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
26880 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
26890 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
268a0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
268b0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
268c0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
268d0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
268e0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
268f0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
26900 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
26910 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
26920 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
26930 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
26940 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
26950 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
26960 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
26970 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
26980 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
26990 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
269a0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
269b0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
269c0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
269d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
269e0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
269f0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
26a00 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
26a10 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
26a20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
26a30 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
26a40 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
26a50 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
26a60 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
26a70 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
26a80 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
26a90 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
26aa0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
26ab0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
26ac0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
26ad0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
26ae0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
26af0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
26b00 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
26b10 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
26b20 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
26b30 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
26b40 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
26b50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
26b60 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
26b70 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
26b80 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
26b90 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
26ba0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
26bb0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
26bc0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
26bd0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
26be0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
26bf0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
26c00 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
26c10 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
26c20 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
26c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
26c40 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
26c50 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
26c60 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
26c70 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
26c80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
26c90 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
26ca0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
26cb0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
26cc0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
26cd0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
26ce0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
26cf0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
26d00 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
26d10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
26d20 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
26d30 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
26d40 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
26d50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26d60 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
26d70 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
26d80 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
26d90 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
26da0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
26db0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
26dc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
26dd0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
26de0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
26df0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
26e00 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
26e10 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
26e20 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
26e30 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
26e40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
26e50 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
26e60 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
26e70 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
26e80 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
26e90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
26ea0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
26eb0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
26ec0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
26ed0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
26ee0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
26ef0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
26f00 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
26f10 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
26f20 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
26f30 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
26f40 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
26f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26f60 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
26f70 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
26f80 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
26f90 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
26fa0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
26fb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
26fc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26fd0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
26fe0 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
26ff0 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
27000 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
27010 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
27020 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
27030 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
27040 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
27050 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27060 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
27070 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
27080 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
27090 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
270a0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
270b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
270c0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
270d0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
270e0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
270f0 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
27100 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
27110 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
27120 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
27130 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
27140 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
27150 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
27160 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
27170 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
27180 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
27190 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
271a0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
271b0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
271c0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
271d0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
271e0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
271f0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
27200 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
27210 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
27220 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
27230 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
27240 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
27250 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
27260 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
27270 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
27280 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
27290 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
272a0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
272b0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
272c0 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
272d0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
272e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
272f0 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
27300 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
27310 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
27320 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
27330 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
27340 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
27350 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
27360 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27370 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
27380 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
27390 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
273a0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
273b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
273c0 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
273d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
273e0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
273f0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
27400 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
27410 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
27420 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
27430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
27440 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
27450 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27460 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
27470 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
27480 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
27490 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
274a0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
274b0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
274c0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
274d0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
274e0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
274f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27500 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
27510 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
27520 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
27530 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
27540 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
27550 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
27560 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
27570 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27580 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
27590 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
275a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
275b0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
275c0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
275d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
275e0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
275f0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
27600 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
27610 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
27620 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
27630 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
27640 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
27650 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
27660 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
27670 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
27680 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
27690 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
276a0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
276b0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
276c0 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61  plementions of a
276d0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
276e0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
276f0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
27700 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
27710 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
27720 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
27730 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
27740 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
27750 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
27760 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
27770 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
27780 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
27790 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
277a0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
277b0 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
277c0 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
277d0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
277e0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
277f0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
27800 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
27810 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
27820 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
27830 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27840 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
27850 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
27860 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
27870 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
27880 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
27890 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
278a0 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
278b0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
278c0 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
278d0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
278e0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
278f0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
27900 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
27910 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
27920 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
27930 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
27940 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
27950 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
27960 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
27970 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
27980 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
27990 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
279a0 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
279b0 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
279c0 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
279d0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
279e0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
279f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
27a00 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
27a10 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
27a20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
27a30 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
27a40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27a50 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27a60 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
27a70 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
27a80 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
27a90 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
27aa0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
27ab0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
27ac0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
27ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
27ae0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
27af0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
27b00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27b10 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
27b20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
27b30 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
27b40 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
27b50 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
27b60 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
27b70 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
27b80 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
27b90 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
27ba0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
27bb0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
27bc0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
27bd0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
27be0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
27bf0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
27c00 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
27c10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
27c20 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
27c30 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
27c40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27c50 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
27c60 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
27c70 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
27c80 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
27c90 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
27ca0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
27cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
27cc0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
27cd0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
27ce0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
27cf0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
27d00 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
27d10 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
27d20 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
27d30 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
27d40 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
27d50 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
27d60 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
27d70 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
27d80 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
27d90 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
27da0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
27db0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
27dc0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27dd0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
27de0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
27df0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
27e00 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
27e10 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
27e20 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
27e30 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
27e40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
27e50 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
27e60 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
27e70 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
27e80 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
27e90 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
27ea0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
27eb0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27ec0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
27ed0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27ee0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
27ef0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
27f00 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
27f10 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
27f20 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
27f30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
27f40 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
27f50 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
27f60 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
27f70 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
27f80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27f90 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
27fa0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
27fb0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
27fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
27fd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27fe0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
27ff0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
28000 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
28010 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28020 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
28030 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
28040 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
28050 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
28060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28070 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
28080 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
28090 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
280a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
280b0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
280c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
280d0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
280e0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
280f0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
28100 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
28110 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
28120 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
28130 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
28140 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
28150 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
28160 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
28170 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
28180 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28190 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
281a0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
281b0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
281c0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
281d0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
281e0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
281f0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
28200 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
28210 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
28220 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
28230 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
28240 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
28250 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
28260 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
28270 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
28280 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
28290 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
282a0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
282b0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
282c0 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
282d0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
282e0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
282f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
28300 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
28310 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
28320 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
28330 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
28340 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
28350 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
28360 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
28370 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
28380 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
28390 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
283a0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
283b0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
283c0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
283d0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
283e0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
283f0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
28400 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
28410 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
28420 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
28430 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
28440 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
28450 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
28460 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
28470 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
28480 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
28490 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
284a0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
284b0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
284c0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
284d0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
284e0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
284f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28500 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
28510 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
28520 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
28530 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
28540 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
28550 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
28560 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
28570 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
28580 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
28590 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
285a0 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
285b0 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
285c0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
285d0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
285e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
285f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
28600 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
28610 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
28620 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
28630 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
28640 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
28650 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
28660 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
28670 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
28680 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28690 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
286a0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
286b0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
286c0 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
286d0 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
286e0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
286f0 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
28700 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
28710 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
28720 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
28730 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
28740 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
28750 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
28760 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
28770 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
28780 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
28790 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
287a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
287b0 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
287c0 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
287d0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
287e0 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
287f0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
28800 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
28810 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
28820 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
28830 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
28840 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
28850 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
28860 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
28870 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
28880 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
28890 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
288a0 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
288b0 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
288c0 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
288d0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
288e0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
288f0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
28900 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
28910 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
28920 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
28930 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
28940 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
28950 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
28960 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
28970 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
28980 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
28990 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
289a0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
289b0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
289c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
289d0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
289e0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
289f0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
28a00 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
28a10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
28a20 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
28a30 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
28a40 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
28a50 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
28a60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
28a70 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
28a80 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
28a90 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
28aa0 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
28ab0 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
28ac0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
28ad0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
28ae0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
28af0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
28b00 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
28b10 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
28b20 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
28b30 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
28b40 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
28b50 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
28b60 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
28b70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
28b80 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
28b90 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
28ba0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
28bb0 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
28bc0 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
28bd0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
28be0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
28bf0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
28c00 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
28c10 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
28c20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
28c30 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
28c40 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
28c50 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
28c60 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
28c70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
28c80 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
28c90 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
28ca0 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
28cb0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
28cc0 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
28cd0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
28ce0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
28cf0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
28d00 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
28d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
28d20 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
28d30 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
28d40 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
28d50 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
28d60 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
28d70 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
28d80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28d90 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
28da0 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
28db0 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
28dc0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
28dd0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
28de0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
28df0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
28e00 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
28e10 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
28e20 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
28e30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28e40 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
28e50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28e60 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
28e70 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
28e80 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
28e90 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
28ea0 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
28eb0 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
28ec0 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
28ed0 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
28ee0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
28ef0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
28f00 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
28f10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28f20 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
28f30 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
28f40 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
28f50 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
28f60 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
28f70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28f80 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
28f90 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
28fa0 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
28fb0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
28fc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28fd0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
28fe0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
28ff0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
29000 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
29010 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
29020 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
29030 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
29040 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
29050 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
29060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
29070 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
29080 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
29090 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
290a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
290b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
290c0 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
290d0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
290e0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
290f0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
29100 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
29110 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
29120 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
29130 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
29140 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
29150 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
29160 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
29170 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
29180 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
29190 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
291a0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
291b0 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
291c0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
291d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
291e0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
291f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29200 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
29210 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
29220 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
29230 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
29240 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
29250 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
29260 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
29270 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
29280 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
29290 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
292a0 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
292b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
292c0 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
292d0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
292e0 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
292f0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
29300 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
29310 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
29320 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
29330 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
29340 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
29350 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
29360 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29370 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
29380 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
29390 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
293a0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
293b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
293c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
293d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
293e0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
293f0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
29400 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
29410 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
29420 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
29430 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
29440 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
29450 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
29460 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
29470 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29480 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
29490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
294a0 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
294b0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
294c0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
294d0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
294e0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
294f0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
29500 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
29510 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
29520 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
29530 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
29540 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29550 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
29560 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
29570 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
29580 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
29590 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
295a0 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
295b0 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
295c0 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
295d0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
295e0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
295f0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
29600 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
29610 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29620 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
29630 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
29640 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
29650 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
29660 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
29670 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
29680 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
29690 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
296a0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
296b0 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
296c0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
296d0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
296e0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
296f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29700 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
29710 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
29720 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
29730 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29740 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
29750 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
29760 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
29770 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
29780 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
29790 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
297a0 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
297b0 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
297c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
297d0 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
297e0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
297f0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
29800 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
29810 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
29820 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
29830 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
29840 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
29850 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
29860 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
29870 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
29880 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29890 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
298a0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
298b0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
298c0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
298d0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
298e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
298f0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
29900 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
29910 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
29920 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
29930 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29940 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
29950 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
29960 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
29970 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
29980 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
29990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
299a0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
299b0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
299c0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
299d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
299e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
299f0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
29a00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29a10 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
29a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29a30 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
29a40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
29a50 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
29a60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
29a70 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
29a80 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
29a90 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
29aa0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29ab0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
29ac0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
29ad0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
29ae0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
29af0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
29b00 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
29b10 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
29b20 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
29b30 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
29b40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
29b50 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
29b60 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
29b70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
29b80 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
29b90 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
29ba0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29bb0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
29bc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
29bd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
29be0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29bf0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
29c00 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
29c10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
29c20 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
29c30 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
29c40 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
29c50 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
29c60 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
29c70 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
29c80 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
29c90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
29ca0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
29cb0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
29cc0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
29cd0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
29ce0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
29cf0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
29d00 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
29d10 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
29d20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
29d30 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
29d40 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  on result..** ^I
29d50 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
29d60 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
29d70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
29d80 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
29d90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29da0 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
29db0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
29dc0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
29dd0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
29de0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
29df0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
29e00 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
29e10 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
29e20 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
29e30 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
29e40 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
29e50 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
29e60 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
29e70 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
29e80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
29e90 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
29ea0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
29eb0 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
29ec0 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
29ed0 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
29ee0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
29ef0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
29f00 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
29f10 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
29f20 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
29f30 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
29f40 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
29f50 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
29f60 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
29f70 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
29f80 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
29f90 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
29fa0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
29fb0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
29fc0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
29fd0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
29fe0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
29ff0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
2a000 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
2a010 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
2a020 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
2a030 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
2a040 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
2a050 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2a060 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
2a070 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2a080 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2a090 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
2a0a0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2a0b0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2a0c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2a0d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2a0e0 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a  be a copy the.**
2a0f0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2a100 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a110 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
2a120 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2a130 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
2a140 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2a150 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
2a160 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
2a170 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2a180 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65  ].** so that the
2a190 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2a1a0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68   specified in th
2a1b0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
2a1c0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20  change or.** be 
2a1d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65  deallocated afte
2a1e0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2a1f0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73  _value() returns
2a200 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
2a210 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20  * ^A [protected 
2a220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a230 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
2a240 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
2a250 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
2a260 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2a270 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
2a280 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
2a290 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
2a2a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a2b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
2a2c0 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
2a2d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
2a2e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2a2f0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
2a300 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
2a310 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
2a320 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
2a330 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a340 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2a350 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
2a360 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2a370 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
2a380 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2a390 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2a3a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a3b0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
2a3c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2a3d0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2a3e0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2a3f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a400 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2a410 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2a420 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
2a430 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
2a440 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2a450 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
2a460 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a470 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
2a480 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2a490 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2a4a0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2a4b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
2a4c0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
2a4d0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2a4e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a4f0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
2a500 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2a510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2a520 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
2a530 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2a540 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a550 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
2a560 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
2a570 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a580 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
2a590 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
2a5a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
2a5b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a5c0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
2a5d0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2a5e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2a5f0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2a600 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2a610 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2a620 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2a630 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a640 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2a650 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2a660 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2a670 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2a680 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a690 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
2a6a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2a6b0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2a6c0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2a6d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a6e0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
2a6f0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2a700 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
2a710 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2a720 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2a730 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
2a740 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
2a750 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
2a760 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
2a770 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
2a780 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
2a790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2a7a0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
2a7b0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
2a7c0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
2a7d0 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20  ons are used to 
2a7e0 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  add new collatio
2a7f0 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74  n sequences to t
2a800 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2a810 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
2a820 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
2a830 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
2a840 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2a850 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
2a860 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
2a870 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
2a880 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
2a890 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a8a0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
2a8b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a8c0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
2a8d0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
2a8e0 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
2a8f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a900 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63  n16(). ^In all c
2a910 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
2a920 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
2a930 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2a940 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2a950 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
2a960 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65  ument may be one
2a970 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
2a980 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  s [SQLITE_UTF8],
2a990 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
2a9a0 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6LE], or [SQLITE
2a9b0 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
2a9c0 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
2a9d0 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
2a9e0 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
2a9f0 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
2aa00 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
2aa10 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
2aa20 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
2aa30 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
2aa40 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
2aa50 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2aa60 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64  y. ^The.** third
2aa70 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20   argument might 
2aa80 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f  also be [SQLITE_
2aa90 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61  UTF16] to indica
2aaa0 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75 74  te that the rout
2aab0 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70  ine.** expects p
2aac0 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54  ointers to be UT
2aad0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20  F-16 strings in 
2aae0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
2aaf0 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a  order, or the.**
2ab00 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65   argument can be
2ab10 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
2ab20 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a  LIGNED] if the.*
2ab30 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
2ab40 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
2ab50 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
2ab60 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
2ab70 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
2ab80 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2ab90 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  der..**.** A poi
2aba0 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72  nter to the user
2abb0 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e   supplied routin
2abc0 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  e must be passed
2abd0 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a   as the fifth.**
2abe0 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
2abf0 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73  it is NULL, this
2ac00 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2ac10 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c  deleting the col
2ac20 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2ac30 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69  ce (so that SQLi
2ac40 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69  te cannot call i
2ac50 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e  t anymore)..** ^
2ac60 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70  Each time the ap
2ac70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69  plication suppli
2ac80 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  ed function is i
2ac90 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61  nvoked, it is pa
2aca0 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66  ssed.** as its f
2acb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61  irst parameter a
2acc0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
2acd0 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  d* passed as the
2ace0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2acf0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2ad00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2ad10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2ad20 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2ad30 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  )..**.** ^The re
2ad40 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
2ad50 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
2ad60 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
2ad70 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
2ad80 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
2ad90 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
2ada0 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
2adb0 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
2adc0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
2add0 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
2ade0 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
2adf0 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
2ae00 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
2ae10 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
2ae20 73 74 65 72 65 64 2e 20 20 54 68 65 20 61 70 70  stered.  The app
2ae30 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
2ae40 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69   collation routi
2ae50 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ne should.** ret
2ae60 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
2ae70 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
2ae80 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
2ae90 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
2aea0 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  .** equal to, or
2aeb0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
2aec0 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e  e second string.
2aed0 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
2aee0 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
2aef0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
2af00 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2af10 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
2af20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2af30 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63  llation().** exc
2af40 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65  ept that it take
2af50 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d  s an extra argum
2af60 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64  ent which is a d
2af70 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a  estructor for.**
2af80 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20   the collation. 
2af90 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2afa0 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   is called when 
2afb0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
2afc0 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e  .** destroyed an
2afd0 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f  d is passed a co
2afe0 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  py of the fourth
2aff0 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a   parameter void*
2b000 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74   pointer.** of t
2b010 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
2b020 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2b030 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73  ..** ^Collations
2b040 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77   are destroyed w
2b050 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65  hen they are ove
2b060 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72  rridden by later
2b070 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
2b080 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74   collation creat
2b090 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  ion functions or
2b0a0 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62   when the [datab
2b0b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b0c0 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69  is closed.** usi
2b0d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ng [sqlite3_clos
2b0e0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  e()]..**.** See 
2b0f0 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
2b100 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b110 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2b120 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b130 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
2b140 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b150 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
2b160 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2b170 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2b180 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2b190 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
2b1a0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
2b1b0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
2b1c0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
2b1d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2b1e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2b1f0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2b200 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2b210 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
2b220 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
2b230 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2b240 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2b250 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2b260 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
2b270 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
2b280 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2b290 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2b2a0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
2b2b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2b2c0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
2b2d0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2b2e0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2b2f0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2b300 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2b310 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
2b320 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
2b330 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
2b340 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
2b350 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
2b360 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
2b370 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2b380 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
2b390 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
2b3a0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
2b3b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
2b3c0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
2b3d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
2b3e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b3f0 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
2b400 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
2b410 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2b420 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
2b430 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2b440 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
2b450 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
2b460 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2b470 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b480 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
2b490 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
2b4a0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
2b4b0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2b4c0 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
2b4d0 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
2b4e0 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
2b4f0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2b500 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
2b510 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
2b520 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
2b530 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
2b540 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2b550 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
2b560 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
2b570 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
2b580 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
2b590 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
2b5a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
2b5b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
2b5c0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
2b5d0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
2b5e0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
2b5f0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
2b600 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2b610 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b620 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
2b630 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2b640 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
2b650 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2b660 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2b670 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
2b680 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2b690 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
2b6a0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2b6b0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
2b6c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2b6d0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
2b6e0 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
2b6f0 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
2b700 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
2b710 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
2b720 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
2b730 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
2b740 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
2b750 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
2b760 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
2b770 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
2b780 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
2b790 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
2b7a0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
2b7b0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
2b7c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b7d0 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
2b7e0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b7f0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
2b800 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b810 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
2b820 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b830 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b840 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2b850 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
2b860 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2b870 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2b880 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
2b890 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
2b8a0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
2b8b0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2b8c0 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
2b8d0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
2b8e0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
2b8f0 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
2b900 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
2b910 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
2b920 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
2b930 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
2b940 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
2b950 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
2b960 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
2b970 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
2b980 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
2b990 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2b9a0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2b9b0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2b9c0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2b9d0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2b9e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
2b9f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2ba00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ba10 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
2ba20 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
2ba30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
2ba40 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
2ba50 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
2ba60 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
2ba70 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
2ba80 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
2ba90 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
2baa0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
2bab0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
2bac0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
2bad0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
2bae0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
2baf0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2bb00 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
2bb10 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2bb20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2bb30 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2bb40 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2bb50 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2bb60 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
2bb70 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
2bb80 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2bb90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
2bba0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
2bbb0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
2bbc0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
2bbd0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
2bbe0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
2bbf0 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  ;../*.** Specify
2bc00 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20   the activation 
2bc10 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61  key for a SEE da
2bc20 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20  tabase.  Unless 
2bc30 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e  .** activated, n
2bc40 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72  one of the SEE r
2bc50 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
2bc60 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
2bc70 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
2bc80 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2bc90 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
2bca0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
2bcb0 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
2bcc0 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
2bcd0 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
2bce0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
2bcf0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
2bd00 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
2bd10 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
2bd20 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
2bd30 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
2bd40 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2bd50 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  rk..*/.void sqli
2bd60 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72  te3_activate_cer
2bd70 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  od(.  const char
2bd80 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20   *zPassPhrase   
2bd90 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69       /* Activati
2bda0 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a  on phrase */.);.
2bdb0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2bdc0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
2bdd0 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
2bde0 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a  Short Time.**.**
2bdf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c   ^The sqlite3_sl
2be00 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  eep() function c
2be10 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e  auses the curren
2be20 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70  t thread to susp
2be30 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a  end execution.**
2be40 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20   for at least a 
2be50 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
2be60 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64  econds specified
2be70 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65   in its paramete
2be80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  r..**.** ^If the
2be90 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2bea0 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
2beb0 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
2bec0 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
2bed0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
2bee0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
2bef0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
2bf00 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
2bf10 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
2bf20 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  . ^The number of
2bf30 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
2bf40 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a   sleep actually.
2bf50 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f  ** requested fro
2bf60 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  m the operating 
2bf70 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e  system is return
2bf80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
2bf90 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
2bfa0 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
2bfb0 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
2bfc0 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
2bfd0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
2bfe0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
2bff0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
2c000 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
2c010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2c020 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
2c030 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
2c040 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
2c050 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
2c060 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
2c070 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
2c080 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
2c090 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
2c0a0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
2c0b0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
2c0c0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
2c0d0 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
2c0e0 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
2c0f0 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
2c100 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
2c110 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
2c120 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
2c130 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
2c140 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2c150 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2c160 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2c170 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
2c180 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
2c190 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
2c1a0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
2c1b0 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
2c1c0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2c1d0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2c1e0 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
2c1f0 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
2c200 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
2c210 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2c220 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2c230 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2c240 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
2c250 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
2c260 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
2c270 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
2c280 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
2c290 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
2c2a0 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
2c2b0 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
2c2c0 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
2c2d0 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
2c2e0 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
2c2f0 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
2c300 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
2c310 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
2c320 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
2c330 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
2c340 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
2c350 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
2c360 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
2c370 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2c380 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
2c390 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
2c3a0 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
2c3b0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2c3c0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2c3d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2c3e0 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
2c3f0 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
2c400 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2c410 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
2c420 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
2c430 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
2c440 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
2c450 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
2c460 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2c470 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
2c480 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
2c490 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
2c4a0 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
2c4b0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
2c4c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
2c4d0 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
2c4e0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
2c4f0 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
2c500 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
2c510 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
2c520 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
2c530 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2c540 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2c550 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
2c560 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
2c570 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
2c580 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2c590 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
2c5a0 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
2c5b0 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
2c5c0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
2c5d0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
2c5e0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
2c5f0 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
2c600 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
2c610 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
2c620 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
2c630 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2c640 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2c650 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2c660 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
2c670 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
2c680 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2c690 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
2c6a0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
2c6b0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2c6c0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2c6d0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2c6e0 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2c6f0 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2c700 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2c710 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
2c720 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2c730 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
2c740 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
2c750 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
2c760 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
2c770 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
2c780 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
2c790 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
2c7a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
2c7b0 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
2c7c0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
2c7d0 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
2c7e0 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
2c7f0 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
2c800 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
2c810 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2c820 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
2c830 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
2c840 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2c850 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2c860 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
2c870 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
2c880 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
2c890 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2c8a0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2c8b0 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
2c8c0 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
2c8d0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
2c8e0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2c8f0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
2c900 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
2c910 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
2c920 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2c930 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
2c940 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
2c950 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
2c960 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
2c970 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
2c980 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2c990 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
2c9a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c9b0 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
2c9c0 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
2c9d0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2c9e0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
2c9f0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2ca00 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
2ca10 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
2ca20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
2ca30 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
2ca40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2ca50 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
2ca60 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
2ca70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
2ca80 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2ca90 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
2caa0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
2cab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
2cac0 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
2cad0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2cae0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2caf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2cb00 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
2cb10 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
2cb20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
2cb30 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
2cb40 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2cb50 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
2cb60 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2cb70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
2cb80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cb90 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
2cba0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cbb0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
2cbc0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2cbd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2cbe0 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
2cbf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
2cc00 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
2cc10 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2cc20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2cc30 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
2cc40 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
2cc50 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
2cc60 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2cc70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
2cc80 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
2cc90 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
2cca0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
2ccb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2ccc0 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
2ccd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cce0 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
2ccf0 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
2cd00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
2cd10 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
2cd20 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
2cd30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2cd40 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
2cd50 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2cd60 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
2cd70 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
2cd80 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2cd90 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
2cda0 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
2cdb0 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
2cdc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
2cdd0 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
2cde0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2cdf0 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
2ce00 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2ce10 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2ce20 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
2ce30 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
2ce40 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
2ce50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ce60 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2ce70 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2ce80 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2ce90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2cea0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2ceb0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2cec0 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
2ced0 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
2cee0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2cef0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2cf00 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
2cf10 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
2cf20 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2cf30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cf40 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2cf50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2cf60 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
2cf70 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2cf80 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
2cf90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2cfa0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
2cfb0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
2cfc0 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
2cfd0 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
2cfe0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
2cff0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
2d000 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
2d010 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
2d020 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2d030 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d040 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2d050 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
2d060 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
2d070 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
2d080 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
2d090 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
2d0a0 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
2d0b0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
2d0c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
2d0d0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
2d0e0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
2d0f0 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
2d100 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2d110 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
2d120 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
2d130 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
2d140 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
2d150 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
2d160 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2d170 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
2d180 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2d190 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
2d1a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2d1b0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
2d1c0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
2d1d0 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
2d1e0 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
2d1f0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2d200 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
2d210 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
2d220 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
2d230 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
2d240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d250 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
2d260 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
2d270 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2d280 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2d290 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d2a0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2d2b0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2d2c0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2d2d0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2d2e0 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2d2f0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
2d300 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
2d310 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
2d320 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
2d330 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2d340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d350 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2d360 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2d370 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2d380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2d390 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2d3a0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2d3b0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2d3c0 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
2d3d0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
2d3e0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
2d3f0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
2d400 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
2d410 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
2d420 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
2d430 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
2d440 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
2d450 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
2d460 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
2d470 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
2d480 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
2d490 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
2d4a0 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
2d4b0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2d4c0 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
2d4d0 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
2d4e0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
2d4f0 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
2d500 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
2d510 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
2d520 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
2d530 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
2d540 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
2d550 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
2d560 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
2d570 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
2d580 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
2d590 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
2d5a0 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
2d5b0 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
2d5c0 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
2d5d0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
2d5e0 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
2d5f0 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
2d600 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
2d610 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
2d620 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
2d630 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
2d640 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
2d650 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
2d660 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
2d670 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2d680 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
2d690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d6a0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
2d6b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
2d6c0 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
2d6d0 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
2d6e0 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
2d6f0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2d700 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
2d710 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
2d720 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
2d730 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
2d740 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
2d750 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
2d760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d770 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
2d780 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2d790 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2d7a0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2d7b0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2d7c0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2d7d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
2d7e0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2d7f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d800 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2d810 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2d820 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
2d830 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
2d840 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2d850 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2d860 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
2d870 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2d880 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
2d890 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
2d8a0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2d8b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d8c0 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2d8d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2d8e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2d8f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
2d900 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
2d910 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
2d920 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2d930 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2d940 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2d950 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2d960 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2d970 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2d980 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2d990 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2d9a0 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
2d9b0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
2d9c0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2d9d0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
2d9e0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
2d9f0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2da00 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
2da10 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2da20 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2da30 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
2da40 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
2da50 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2da60 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
2da70 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2da80 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
2da90 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
2daa0 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
2dab0 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
2dac0 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
2dad0 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
2dae0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
2daf0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
2db00 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
2db10 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
2db20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
2db30 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
2db40 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
2db50 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
2db60 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
2db70 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2db80 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2db90 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2dba0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2dbb0 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2dbc0 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2dbd0 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
2dbe0 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
2dbf0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
2dc00 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
2dc10 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
2dc20 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
2dc30 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
2dc40 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
2dc50 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
2dc60 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
2dc70 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
2dc80 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
2dc90 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2dca0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2dcb0 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2dcc0 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2dcd0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2dce0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2dcf0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2dd00 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2dd10 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2dd20 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2dd30 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2dd40 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2dd50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2dd60 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2dd70 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2dd80 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2dd90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dda0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2ddb0 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2ddc0 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2ddd0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2dde0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ddf0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2de00 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2de10 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2de20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2de30 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2de40 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2de50 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2de60 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2de70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2de80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2de90 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2dea0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2deb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2dec0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2ded0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2dee0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2def0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2df00 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
2df10 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
2df20 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
2df30 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
2df40 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
2df50 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
2df60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2df70 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
2df80 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
2df90 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
2dfa0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2dfb0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2dfc0 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
2dfd0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2dfe0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2dff0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
2e000 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2e010 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2e020 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
2e030 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
2e040 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
2e050 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
2e060 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
2e070 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2e080 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
2e090 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
2e0a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
2e0b0 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
2e0c0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2e0d0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2e0e0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2e0f0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2e100 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2e110 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2e120 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
2e130 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e140 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
2e150 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
2e160 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
2e170 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2e180 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2e190 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
2e1a0 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2e1b0 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
2e1c0 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
2e1d0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2e1e0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
2e1f0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
2e200 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
2e210 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2e220 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2e230 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
2e240 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
2e250 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
2e260 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2e270 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
2e280 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
2e290 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
2e2a0 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
2e2b0 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
2e2c0 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
2e2d0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
2e2e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e2f0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2e300 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
2e310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
2e320 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
2e330 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
2e340 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
2e350 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
2e360 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
2e370 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
2e380 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
2e390 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
2e3a0 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2e3b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2e3c0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
2e3d0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
2e3e0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
2e3f0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
2e400 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2e410 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
2e420 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
2e430 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2e440 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2e450 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2e460 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2e470 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2e480 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2e490 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2e4a0 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2e4b0 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2e4c0 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2e4d0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2e4e0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2e4f0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2e500 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
2e510 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
2e520 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
2e530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e540 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
2e550 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
2e560 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e570 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2e580 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2e590 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
2e5a0 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
2e5b0 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
2e5c0 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
2e5d0 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
2e5e0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
2e5f0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
2e600 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
2e610 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
2e620 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
2e630 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
2e640 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
2e650 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
2e660 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
2e670 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
2e680 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
2e690 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2e6a0 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
2e6b0 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
2e6c0 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
2e6d0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
2e6e0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
2e6f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e700 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2e710 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2e720 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20  I3REF: Impose A 
2e730 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
2e740 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ze.**.** ^The sq
2e750 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
2e760 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
2e770 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  e places a "soft
2e780 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68  " limit.** on th
2e790 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
2e7a0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
2e7b0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
2e7c0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20   SQLite..** ^If 
2e7d0 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
2e7e0 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
2e7f0 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
2e800 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
2e810 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
2e820 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2e830 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
2e840 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
2e850 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
2e860 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
2e870 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
2e880 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
2e890 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69  d..**.** ^The li
2e8a0 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
2e8b0 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20  oft" because if 
2e8c0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2e8d0 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
2e8e0 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
2e8f0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
2e900 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
2e910 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
2e920 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
2e930 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
2e940 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
2e950 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
2e960 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
2e970 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72  * ^A negative or
2e980 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
2e990 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
2e9a0 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
2e9b0 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
2e9c0 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2e9d0 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
2e9e0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2e9f0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
2ea00 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  hausted..** ^The
2ea10 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2ea20 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2ea30 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2ea40 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d  **.** ^(SQLite m
2ea50 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2ea60 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2ea70 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2ea80 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2ea90 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2eaa0 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2eab0 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2eac0 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2ead0 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2eae0 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54  tification.)^  T
2eaf0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
2eb00 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  imit is.** calle
2eb10 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  d a "soft" limit
2eb20 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72  .  It is advisor
2eb30 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72  y only..**.** Pr
2eb40 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
2eb50 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69  rsion 3.5.0, thi
2eb60 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63  s routine only c
2eb70 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d  onstrained the m
2eb80 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2eb90 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ed by a single t
2eba0 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65  hread - the same
2ebb0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2ebc0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
2ebd0 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e   runs.  Beginnin
2ebe0 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
2ebf0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65  rsion 3.5.0, the
2ec00 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2ec10 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74   is.** applied t
2ec20 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54  o all threads. T
2ec30 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  he value specifi
2ec40 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ed for the soft 
2ec50 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73  heap limit.** is
2ec60 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
2ec70 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d  on the total mem
2ec80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2ec90 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  or all threads. 
2eca0 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
2ecb0 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
2ecc0 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
2ecd0 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
2ece0 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
2ecf0 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
2ed00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2ed10 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2ed20 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2ed30 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
2ed40 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
2ed50 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
2ed60 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  le.**.** ^This r
2ed70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2ed80 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2ed90 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2eda0 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2edb0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2edc0 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2edd0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ede0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2edf0 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2ee00 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2ee10 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2ee20 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
2ee30 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2ee40 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2ee50 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2ee60 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2ee70 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65  s function. ^The
2ee80 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ee90 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
2eea0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2eeb0 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
2eec0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72  ain", "temp", or
2eed0 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
2eee0 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
2eef0 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
2ef00 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
2ef10 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  . ^If it is NULL
2ef20 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
2ef30 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
2ef40 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
2ef50 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
2ef60 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
2ef70 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
2ef80 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2ef90 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
2efa0 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
2efb0 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
2efc0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
2efd0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2efe0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2eff0 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
2f000 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
2f010 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
2f020 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
2f030 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
2f040 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
2f050 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
2f060 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65   NULL..**.** ^Me
2f070 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
2f080 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
2f090 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
2f0a0 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
2f0b0 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
2f0c0 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
2f0d0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2f0e0 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74  ction. ^Any of t
2f0f0 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
2f100 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
2f110 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2f120 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
2f130 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61  lement of metada
2f140 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  ta is omitted..*
2f150 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f  *.** ^(<blockquo
2f160 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2f170 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2f180 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20  ><th> Parameter 
2f190 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54  <th> Output<br>T
2f1a0 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69  ype <th>  Descri
2f1b0 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  ption.**.** <tr>
2f1c0 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f  <td> 5th <td> co
2f1d0 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44  nst char* <td> D
2f1e0 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e  ata type.** <tr>
2f1f0 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f  <td> 6th <td> co
2f200 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e  nst char* <td> N
2f210 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63  ame of default c
2f220 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2f230 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74  e.** <tr><td> 7t
2f240 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2f250 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2f260 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
2f270 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2f280 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68  .** <tr><td> 8th
2f290 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2f2a0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2f2b0 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
2f2c0 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
2f2d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68  .** <tr><td> 9th
2f2e0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2f2f0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2f300 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e  olumn is [AUTOIN
2f310 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61  CREMENT].** </ta
2f320 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2f330 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
2f340 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
2f350 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
2f360 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
2f370 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
2f380 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
2f390 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
2f3a0 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
2f3b0 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
2f3c0 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
2f3d0 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
2f3e0 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
2f3f0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2f400 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
2f410 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
2f420 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2f430 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2f440 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2f450 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
2f460 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
2f470 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a  _rowid_" and an.
2f480 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ** [INTEGER PRIM
2f490 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20  ARY KEY] column 
2f4a0 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
2f4b0 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
2f4c0 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2f4d0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2f4e0 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
2f4f0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2f500 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65  column. ^(If the
2f510 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
2f520 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2f530 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2f540 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
2f550 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2f560 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2f570 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
2f580 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
2f590 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
2f5a0 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
2f5b0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2f5c0 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
2f5d0 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
2f5e0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
2f5f0 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
2f600 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
2f610 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
2f620 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
2f630 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
2f640 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
2f650 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
2f660 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
2f670 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2f680 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
2f690 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
2f6a0 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2f6b0 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
2f6c0 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
2f6d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2f6e0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
2f6f0 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
2f700 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2f710 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
2f720 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
2f730 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
2f740 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()).)^.**.** ^Th
2f750 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
2f760 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2f770 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2f780 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2f790 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2f7a0 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2f7b0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2f7c0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
2f7d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
2f7e0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
2f7f0 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
2f800 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2f810 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
2f820 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
2f830 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
2f840 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
2f850 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
2f860 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
2f870 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
2f880 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
2f890 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2f8a0 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
2f8b0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
2f8c0 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2f8d0 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
2f8e0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
2f8f0 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
2f900 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
2f910 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
2f920 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
2f930 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2f940 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
2f950 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
2f960 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2f970 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
2f980 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
2f990 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
2f9a0 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
2f9b0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2f9c0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
2f9d0 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
2f9e0 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
2f9f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2fa00 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
2fa10 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
2fa20 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
2fa30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
2fa40 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
2fa50 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2fa60 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53  rface loads an S
2fa70 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
2fa80 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65  library from the
2fa90 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a   named file..**.
2faa0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fab0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2fac0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2fad0 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a  pts to load an.*
2fae0 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  * SQLite extensi
2faf0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
2fb00 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
2fb10 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   zFile..**.** ^T
2fb20 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
2fb30 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72  s zProc..** ^zPr
2fb40 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20  oc may be 0, in 
2fb50 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
2fb60 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79  ame of the entry
2fb70 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c   point.** defaul
2fb80 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
2fb90 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
2fba0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fbb0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2fbc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fbd0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ns.** [SQLITE_OK
2fbe0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
2fbf0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2fc00 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
2fc10 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20  s wrong..** ^If 
2fc20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
2fc30 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
2fc40 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
2fc50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  ** [sqlite3_load
2fc60 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
2fc70 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
2fc80 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c  tempt to.** fill
2fc90 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
2fca0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2fcb0 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
2fcc0 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
2fcd0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2fce0 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c  lloc()]. The cal
2fcf0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ling function.**
2fd00 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
2fd10 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
2fd20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2fd30 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74  e()]..**.** ^Ext
2fd40 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
2fd50 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
2fd60 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2fd70 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
2fd80 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
2fd90 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
2fda0 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73  API,.** otherwis
2fdb0 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
2fdc0 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  be returned..**.
2fdd0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2fde0 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
2fdf0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
2fe00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2fe10 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
2fe20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2fe30 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
2fe40 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
2fe50 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
2fe60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
2fe70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
2fe80 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
2fe90 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
2fea0 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
2feb0 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
2fec0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
2fed0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
2fee0 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
2fef0 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
2ff00 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
2ff10 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
2ff20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
2ff30 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
2ff40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ff50 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
2ff60 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
2ff70 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
2ff80 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
2ff90 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
2ffa0 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
2ffb0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
2ffc0 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
2ffd0 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
2ffe0 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
2fff0 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
30000 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
30010 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
30020 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
30030 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
30040 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
30050 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
30060 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
30070 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
30080 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
30090 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
300a0 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
300b0 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
300c0 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
300d0 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
300e0 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
300f0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
30100 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
30110 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
30120 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
30130 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
30140 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
30150 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
30160 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
30170 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  again..*/.int sq
30180 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
30190 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
301a0 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
301b0 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
301c0 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61  3REF: Automatica
301d0 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
301e0 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  nsions.**.** ^Th
301f0 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e  is API can be in
30200 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d  voked at program
30210 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65   startup in orde
30220 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  r to register.**
30230 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61   one or more sta
30240 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65  tically linked e
30250 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77  xtensions that w
30260 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65  ill be available
30270 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b  .** to all new [
30280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30290 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ions]..**.** ^(T
302a0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
302b0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
302c0 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e  the extension en
302d0 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20  try point.** in 
302e0 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73  an array that is
302f0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
30300 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
30310 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a  ].  That memory.
30320 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65  ** is deallocate
30330 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65  d by [sqlite3_re
30340 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
30350 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  on()].)^.**.** ^
30360 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
30370 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
30380 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
30390 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f   that is.** auto
303a0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
303b0 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
303c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
303d0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65  ction].** is ope
303e0 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ned using [sqlit
303f0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
30400 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
30410 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
30420 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44  pen_v2()]..** ^D
30430 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
30440 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
30450 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
30460 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74   routine.** mult
30470 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20  iple times with 
30480 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69  the same extensi
30490 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a  on is harmless..
304a0 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78  ** ^Automatic ex
304b0 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
304c0 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
304d0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
304e0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
304f0 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
30500 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
30510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
30520 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
30530 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
30540 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
30550 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
30560 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
30570 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
30580 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
30590 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20  . It undoes the 
305a0 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
305b0 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ior.** [sqlite3_
305c0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
305d0 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a  ] calls.)^.**.**
305e0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
305f0 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
30600 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
30610 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
30620 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
30630 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
30640 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
30650 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
30660 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
30670 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73  ble mechanism is
30680 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
30690 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
306a0 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
306b0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
306c0 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
306d0 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
306e0 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
306f0 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
30700 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
30710 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
30720 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
30730 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
30740 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
30750 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
30760 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
30770 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
30780 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
30790 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
307a0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
307b0 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74  nt..*/../*.** St
307c0 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79  ructures used by
307d0 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
307e0 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a  le interface.*/.
307f0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
30800 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69  qlite3_vtab sqli
30810 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65  te3_vtab;.typede
30820 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
30830 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69  _index_info sqli
30840 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a  te3_index_info;.
30850 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
30860 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30870 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  or sqlite3_vtab_
30880 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20  cursor;.typedef 
30890 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
308a0 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f  odule sqlite3_mo
308b0 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  dule;../*.** CAP
308c0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
308d0 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  able Object.** K
308e0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
308f0 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c  _module {virtual
30900 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a   table module}.*
30910 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74  *.** This struct
30920 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63  ure, sometimes c
30930 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75  alled a a "virtu
30940 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
30950 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
30960 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30970 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
30980 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
30990 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
309a0 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
309b0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
309c0 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  odule..**.** ^A 
309d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
309e0 64 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20  dule is created 
309f0 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20  by filling in a 
30a00 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e  persistent.** in
30a10 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
30a20 74 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73  tructure and pas
30a30 73 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74  sing a pointer t
30a40 6f 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a  o that instance.
30a50 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
30a60 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
30a70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
30a80 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e  te_module_v2()].
30a90 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72  .** ^The registr
30aa0 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61  ation remains va
30ab0 6c 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20  lid until it is 
30ac0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69  replaced by a di
30ad0 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c  fferent.** modul
30ae0 65 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b  e or until the [
30af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30b00 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68  ion] closes.  Th
30b10 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20  e content.** of 
30b20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d  this structure m
30b30 75 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77  ust not change w
30b40 68 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73  hile it is regis
30b50 74 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e  tered with.** an
30b60 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
30b70 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74  ction..*/.struct
30b80 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
30b90 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
30ba0 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74  ;.  int (*xCreat
30bb0 65 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  e)(sqlite3*, voi
30bc0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
30bd0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
30be0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
30bf0 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
30c00 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
30c10 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
30c20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
30c30 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74  *xConnect)(sqlit
30c40 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
30c50 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30c60 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
30c70 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
30c80 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30c90 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
30ca0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
30cb0 0a 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e  .  int (*xBestIn
30cc0 64 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61  dex)(sqlite3_vta
30cd0 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
30ce0 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a  3_index_info*);.
30cf0 20 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e    int (*xDisconn
30d00 65 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ect)(sqlite3_vta
30d10 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30d20 20 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c   (*xDestroy)(sql
30d30 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
30d40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  );.  int (*xOpen
30d50 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
30d60 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76  pVTab, sqlite3_v
30d70 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43  tab_cursor **ppC
30d80 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ursor);.  int (*
30d90 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
30da0 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20  vtab_cursor*);. 
30db0 20 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28   int (*xFilter)(
30dc0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
30dd0 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d  sor*, int idxNum
30de0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64  , const char *id
30df0 78 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20  xStr,.          
30e00 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
30e10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a  sqlite3_value **
30e20 61 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78  argv);.  int (*x
30e30 4e 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74  Next)(sqlite3_vt
30e40 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
30e50 6e 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74  nt (*xEof)(sqlit
30e60 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
30e70 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d  ;.  int (*xColum
30e80 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  n)(sqlite3_vtab_
30e90 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33  cursor*, sqlite3
30ea0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
30eb0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29  .  int (*xRowid)
30ec0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
30ed0 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  rsor*, sqlite3_i
30ee0 6e 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20  nt64 *pRowid);. 
30ef0 20 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28   int (*xUpdate)(
30f00 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20  sqlite3_vtab *, 
30f10 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  int, sqlite3_val
30f20 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69  ue **, sqlite3_i
30f30 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28  nt64 *);.  int (
30f40 2a 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33  *xBegin)(sqlite3
30f50 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
30f60 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
30f70 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30f80 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d  b);.  int (*xCom
30f90 6d 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  mit)(sqlite3_vta
30fa0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
30fb0 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71   (*xRollback)(sq
30fc0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30fd0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e  b);.  int (*xFin
30fe0 64 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74  dFunction)(sqlit
30ff0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
31000 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20  int nArg, const 
31010 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20  char *zName,.   
31020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31030 20 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75      void (**pxFu
31040 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
31050 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
31060 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20  _value**),.     
31070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31080 20 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b    void **ppArg);
31090 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65  .  int (*xRename
310a0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
310b0 70 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61  pVtab, const cha
310c0 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a  r *zNew);.};../*
310d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
310e0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65  rtual Table Inde
310f0 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e  xing Information
31100 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
31110 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
31120 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31130 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
31140 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
31150 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
31160 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73   used to.** pass
31170 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
31180 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
31190 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
311a0 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a   [xBestIndex].**
311b0 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69   method of a [vi
311c0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
311d0 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73  le].  The fields
311e0 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
311f0 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
31200 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
31210 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
31220 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
31230 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
31240 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
31250 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
31260 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  lds..**.** ^(The
31270 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
31280 72 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45  rray records WHE
31290 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
312a0 61 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  aints of the for
312b0 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f  m:.**.** <pre>co
312c0 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72  lumn OP expr</pr
312d0 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f  e>.**.** where O
312e0 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c  P is =, &lt;, &l
312f0 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67  t;=, &gt;, or &g
31300 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61  t;=.)^  ^(The pa
31310 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
31320 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69  r is.** stored i
31330 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
31340 6f 70 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e 64  op.)^  ^(The ind
31350 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
31360 20 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a   is stored in.**
31370 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69   aConstraint[].i
31380 43 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f  Column.)^  ^(aCo
31390 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c  nstraint[].usabl
313a0 65 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65  e is TRUE if the
313b0 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20  .** expr on the 
313c0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
313d0 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64  can be evaluated
313e0 20 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63   (and thus the c
313f0 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20  onstraint.** is 
31400 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73  usable) and fals
31410 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29  e if it cannot.)
31420 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74  ^.**.** ^The opt
31430 69 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63  imizer automatic
31440 61 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72  ally inverts ter
31450 6d 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ms of the form "
31460 65 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a  expr OP column".
31470 2a 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68  ** and makes oth
31480 65 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f  er simplificatio
31490 6e 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20  ns to the WHERE 
314a0 63 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74  clause in an att
314b0 65 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61  empt to.** get a
314c0 73 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61  s many WHERE cla
314d0 75 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74  use terms into t
314e0 68 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62  he form shown ab
314f0 6f 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e  ove as possible.
31500 0a 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72  .** ^The aConstr
31510 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c  aint[] array onl
31520 79 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20  y reports WHERE 
31530 63 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61  clause terms tha
31540 74 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e  t are.** relevan
31550 74 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75  t to the particu
31560 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c  lar virtual tabl
31570 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e  e being queried.
31580 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74  .**.** ^Informat
31590 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52  ion about the OR
315a0 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73  DER BY clause is
315b0 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65   stored in aOrde
315c0 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20  rBy[]..** ^Each 
315d0 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79  term of aOrderBy
315e0 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d   records a colum
315f0 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42  n of the ORDER B
31600 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  Y clause..**.** 
31610 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  The [xBestIndex]
31620 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c   method must fil
31630 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  l aConstraintUsa
31640 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d  ge[] with inform
31650 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77  ation.** about w
31660 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  hat parameters t
31670 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65  o pass to xFilte
31680 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65  r.  ^If argvInde
31690 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  x>0 then.** the 
316a0 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20  right-hand side 
316b0 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  of the correspon
316c0 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74  ding aConstraint
316d0 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a  [] is evaluated.
316e0 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74  ** and becomes t
316f0 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20  he argvIndex-th 
31700 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20  entry in argv.  
31710 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74  ^(If aConstraint
31720 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20  Usage[].omit.** 
31730 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68  is true, then th
31740 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  e constraint is 
31750 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75  assumed to be fu
31760 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74  lly handled by t
31770 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61  he.** virtual ta
31780 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63  ble and is not c
31790 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20  hecked again by 
317a0 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  SQLite.)^.**.** 
317b0 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20  ^The idxNum and 
317c0 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72  idxPtr values ar
317d0 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70  e recorded and p
317e0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a  assed into the.*
317f0 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68  * [xFilter] meth
31800 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33  od..** ^[sqlite3
31810 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64  _free()] is used
31820 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20   to free idxPtr 
31830 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
31840 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50  * needToFreeIdxP
31850 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a  tr is true..**.*
31860 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f  * ^The orderByCo
31870 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61  nsumed means tha
31880 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78  t output from [x
31890 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20  Filter]/[xNext] 
318a0 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a  will occur in.**
318b0 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64   the correct ord
318c0 65 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68  er to satisfy th
318d0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
318e0 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70  e so that no sep
318f0 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67  arate.** sorting
31900 20 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65   step is require
31910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73  d..**.** ^The es
31920 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75  timatedCost valu
31930 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65  e is an estimate
31940 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20   of the cost of 
31950 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72  doing the.** par
31960 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20  ticular lookup. 
31970 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20   A full scan of 
31980 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65  a table with N e
31990 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
319a0 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20  ve.** a cost of 
319b0 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61  N.  A binary sea
319c0 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f  rch of a table o
319d0 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75  f N entries shou
319e0 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73  ld have a.** cos
319f0 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65  t of approximate
31a00 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74  ly log(N)..*/.st
31a10 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
31a20 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49  ex_info {.  /* I
31a30 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  nputs */.  int n
31a40 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
31a50 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
31a60 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43  of entries in aC
31a70 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73  onstraint */.  s
31a80 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
31a90 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b  dex_constraint {
31aa0 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d  .     int iColum
31ab0 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  n;              
31ac0 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66  /* Column on lef
31ad0 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63  t-hand side of c
31ae0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20  onstraint */.   
31af0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
31b00 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43  op;         /* C
31b10 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74  onstraint operat
31b20 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  or */.     unsig
31b30 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b  ned char usable;
31b40 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
31b50 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20  this constraint 
31b60 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20  is usable */.   
31b70 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65    int iTermOffse
31b80 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55  t;          /* U
31b90 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d  sed internally -
31ba0 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75   xBestIndex shou
31bb0 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d  ld ignore */.  }
31bc0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20   *aConstraint;  
31bd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62            /* Tab
31be0 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75  le of WHERE clau
31bf0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a  se constraints *
31c00 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79  /.  int nOrderBy
31c10 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
31c20 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  * Number of term
31c30 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42  s in the ORDER B
31c40 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74  Y clause */.  st
31c50 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
31c60 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20  ex_orderby {.   
31c70 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20    int iColumn;  
31c80 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
31c90 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  olumn number */.
31ca0 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68       unsigned ch
31cb0 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f  ar desc;       /
31cc0 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e  * True for DESC.
31cd0 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e    False for ASC.
31ce0 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42   */.  } *aOrderB
31cf0 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
31d00 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59   /* The ORDER BY
31d10 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20   clause */.  /* 
31d20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72  Outputs */.  str
31d30 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
31d40 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61  x_constraint_usa
31d50 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67  ge {.    int arg
31d60 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20  vIndex;         
31d70 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73    /* if >0, cons
31d80 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f  traint is part o
31d90 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65  f argv to xFilte
31da0 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65  r */.    unsigne
31db0 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20  d char omit;    
31dc0 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65    /* Do not code
31dd0 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73   a test for this
31de0 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
31df0 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55   } *aConstraintU
31e00 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e  sage;.  int idxN
31e10 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  um;             
31e20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65     /* Number use
31e30 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68  d to identify th
31e40 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61  e index */.  cha
31e50 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20  r *idxStr;      
31e60 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e          /* Strin
31e70 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61  g, possibly obta
31e80 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
31e90 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e  3_malloc */.  in
31ea0 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53  t needToFreeIdxS
31eb0 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65  tr;      /* Free
31ec0 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71   idxStr using sq
31ed0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20  lite3_free() if 
31ee0 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72  true */.  int or
31ef0 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20  derByConsumed;  
31f00 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20       /* True if 
31f10 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64  output is alread
31f20 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64  y ordered */.  d
31f30 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43  ouble estimatedC
31f40 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74  ost;      /* Est
31f50 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75  imated cost of u
31f60 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20  sing this index 
31f70 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51  */.};.#define SQ
31f80 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
31f90 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
31fa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
31fb0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
31fc0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
31fd0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
31fe0 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
31ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32000 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
32010 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
32020 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
32030 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
32040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
32050 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
32060 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
32070 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
32080 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  er A Virtual Tab
32090 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le Implementatio
320a0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
320b0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
320c0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e   to register a n
320d0 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ew [virtual tabl
320e0 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a  e module] name..
320f0 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73  ** ^Module names
32100 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65   must be registe
32110 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72  red before.** cr
32120 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69  eating a new [vi
32130 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69  rtual table] usi
32140 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  ng the module an
32150 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61  d before using a
32160 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20  .** preexisting 
32170 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
32180 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
32190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c  **.** ^The modul
321a0 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74  e name is regist
321b0 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74  ered on the [dat
321c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
321d0 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  ] specified.** b
321e0 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
321f0 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d  meter.  ^The nam
32200 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
32210 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  is given by the 
32220 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
32230 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72  eter.  ^The thir
32240 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
32250 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74   pointer to.** t
32260 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32270 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  n of the [virtua
32280 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
32290 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a     ^The fourth.*
322a0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  * parameter is a
322b0 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65  n arbitrary clie
322c0 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  nt data pointer 
322d0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74  that is passed t
322e0 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74  hrough.** into t
322f0 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
32300 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
32310 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75  ods of the virtu
32320 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a  al table module.
32330 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69  ** when a new vi
32340 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62  rtual table is b
32350 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20  e being created 
32360 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64  or reinitialized
32370 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32380 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
32390 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  le_v2() interfac
323a0 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61  e has a fifth pa
323b0 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
323c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
323d0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
323e0 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  r the pClientDat
323f0 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  a.  ^SQLite will
32400 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  .** invoke the d
32410 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
32420 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74  on (if it is not
32430 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69   NULL) when SQLi
32440 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20  te.** no longer 
32450 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e  needs the pClien
32460 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20  tData pointer.  
32470 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
32480 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20  ate_module().** 
32490 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75  interface is equ
324a0 69 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74  ivalent to sqlit
324b0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
324c0 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c  _v2() with a NUL
324d0 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e  L.** destructor.
324e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
324f0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20  create_module(. 
32500 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
32510 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
32520 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
32530 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
32540 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
32550 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
32560 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
32570 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
32580 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
32590 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
325a0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
325b0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
325c0 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20  id *pClientData 
325d0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
325e0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
325f0 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
32600 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32610 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
32620 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
32630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32640 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69   SQLite connecti
32650 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  on to register m
32660 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20  odule with */.  
32670 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
32680 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  e,         /* Na
32690 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
326a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69   */.  const sqli
326b0 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20  te3_module *p,  
326c0 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
326d0 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
326e0 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74  void *pClientDat
326f0 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c  a,         /* Cl
32700 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43  ient data for xC
32710 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a  reate/xConnect *
32720 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  /.  void(*xDestr
32730 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f  oy)(void*)     /
32740 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63  * Module destruc
32750 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  tor function */.
32760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32770 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
32780 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63  e Instance Objec
32790 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
327a0 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a  qlite3_vtab.**.*
327b0 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c  * Every [virtual
327c0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69   table module] i
327d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
327e0 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a  es a subclass.**
327f0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
32800 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61  to describe a pa
32810 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
32820 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72  e.** of the [vir
32830 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61  tual table].  Ea
32840 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c  ch subclass will
32850 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20  .** be tailored 
32860 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
32870 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64  needs of the mod
32880 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
32890 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f  on..** The purpo
328a0 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
328b0 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
328c0 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
328d0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f  s that are.** co
328e0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  mmon to all modu
328f0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
32900 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75  ns..**.** ^Virtu
32910 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64  al tables method
32920 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72  s can set an err
32930 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73  or message by as
32940 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72  signing a.** str
32950 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
32960 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
32970 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67  tf()] to zErrMsg
32980 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68  .  The method sh
32990 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72  ould.** take car
329a0 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72  e that any prior
329b0 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64   string is freed
329c0 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73   by a call to [s
329d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a  qlite3_free()].*
329e0 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67  * prior to assig
329f0 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e  ning a new strin
32a00 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e  g to zErrMsg.  ^
32a10 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  After the error 
32a20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65  message.** is de
32a30 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68  livered up to th
32a40 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61  e client applica
32a50 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67  tion, the string
32a60 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
32a70 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20  ically.** freed 
32a80 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  by sqlite3_free(
32a90 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73  ) and the zErrMs
32aa0 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20  g field will be 
32ab0 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63  zeroed..*/.struc
32ac0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b  t sqlite3_vtab {
32ad0 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
32ae0 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65  _module *pModule
32af0 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65  ;  /* The module
32b00 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61   for this virtua
32b10 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74  l table */.  int
32b20 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20   nRef;          
32b30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32b40 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a  NO LONGER USED *
32b50 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  /.  char *zErrMs
32b60 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g;              
32b70 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73      /* Error mes
32b80 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  sage from sqlite
32b90 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20  3_mprintf() */. 
32ba0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
32bb0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32bc0 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
32bd0 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
32be0 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
32bf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
32c00 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73  rtual Table Curs
32c10 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  or Object.** KEY
32c20 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
32c30 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74  tab_cursor {virt
32c40 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72  ual table cursor
32c50 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  }.**.** Every [v
32c60 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
32c70 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
32c80 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
32c90 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ass of the.** fo
32ca0 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72  llowing structur
32cb0 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75  e to describe cu
32cc0 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74  rsors that point
32cd0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69   into the.** [vi
32ce0 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64  rtual table] and
32cf0 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20   are used.** to 
32d00 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65  loop through the
32d10 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20   virtual table. 
32d20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65   Cursors are cre
32d30 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ated using the.*
32d40 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  * [sqlite3_modul
32d50 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d  e.xOpen | xOpen]
32d60 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d   method of the m
32d70 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65  odule and are de
32d80 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68  stroyed.** by th
32d90 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  e [sqlite3_modul
32da0 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73  e.xClose | xClos
32db0 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73  e] method.  Curs
32dc0 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  ors are used.** 
32dd0 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d  by the [xFilter]
32de0 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66  , [xNext], [xEof
32df0 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e  ], [xColumn], an
32e00 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f  d [xRowid] metho
32e10 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64  ds.** of the mod
32e20 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c  ule.  Each modul
32e30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32e40 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20   will define.** 
32e50 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61  the content of a
32e60 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72   cursor structur
32e70 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77  e to suit its ow
32e80 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  n needs..**.** T
32e90 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65  his superclass e
32ea0 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74  xists in order t
32eb0 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20  o define fields 
32ec0 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68  of the cursor th
32ed0 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e  at.** are common
32ee0 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e   to all implemen
32ef0 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75  tations..*/.stru
32f00 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
32f10 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74  cursor {.  sqlit
32f20 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20  e3_vtab *pVtab; 
32f30 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20       /* Virtual 
32f40 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75  table of this cu
32f50 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  rsor */.  /* Vir
32f60 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
32f70 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
32f80 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
32f90 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
32fa0 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
32fb0 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54  I3REF: Declare T
32fc0 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56  he Schema Of A V
32fd0 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a  irtual Table.**.
32fe0 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65  ** ^The [xCreate
32ff0 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d  ] and [xConnect]
33000 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a   methods of a.**
33010 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
33020 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69  module] call thi
33030 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  s interface.** t
33040 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f  o declare the fo
33050 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20  rmat (the names 
33060 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66  and datatypes of
33070 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66   the columns) of
33080 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20  .** the virtual 
33090 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c  tables they impl
330a0 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ement..*/.int sq
330b0 6c 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74  lite3_declare_vt
330c0 61 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  ab(sqlite3*, con
330d0 73 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a  st char *zSQL);.
330e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
330f0 20 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63   Overload A Func
33100 74 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75  tion For A Virtu
33110 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e  al Table.**.** ^
33120 28 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20  (Virtual tables 
33130 63 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65  can provide alte
33140 72 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e  rnative implemen
33150 74 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74  tations of funct
33160 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ions.** using th
33170 65 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e  e [xFindFunction
33180 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
33190 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
331a0 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74  odule].  .** But
331b0 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73   global versions
331c0 20 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69   of those functi
331d0 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73  ons.** must exis
331e0 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65  t in order to be
331f0 20 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a   overloaded.)^.*
33200 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20  *.** ^(This API 
33210 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f  makes sure a glo
33220 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61  bal version of a
33230 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
33240 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e   particular.** n
33250 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f  ame and number o
33260 66 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69  f parameters exi
33270 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68  sts.  If no such
33280 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73   function exists
33290 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20  .** before this 
332a0 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61  API is called, a
332b0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
332c0 20 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68   created.)^  ^Th
332d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
332e0 0a 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66  .** of the new f
332f0 75 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63  unction always c
33300 61 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69  auses an excepti
33310 6f 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e  on to be thrown.
33320 20 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20    So.** the new 
33330 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
33340 67 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e  good for anythin
33350 67 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74  g by itself.  It
33360 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73  s only.** purpos
33370 65 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61  e is to be a pla
33380 63 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f  ceholder functio
33390 6e 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  n that can be ov
333a0 65 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61  erloaded.** by a
333b0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
333c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
333d0 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69  _overload_functi
333e0 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e  on(sqlite3*, con
333f0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61  st char *zFuncNa
33400 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a  me, int nArg);..
33410 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
33420 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
33430 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
33440 73 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65  sm defined above
33450 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20   (back up.** to 
33460 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b  a comment remark
33470 61 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20  ably similar to 
33480 74 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72  this one) is cur
33490 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
334a0 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
334b0 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
334c0 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
334d0 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
334e0 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
334f0 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
33500 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
33510 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
33520 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
33530 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
33540 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
33550 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
33560 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
33570 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
33580 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
33590 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
335a0 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
335b0 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
335c0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
335d0 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20  EF: A Handle To 
335e0 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20  An Open BLOB.** 
335f0 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20  KEYWORDS: {BLOB 
33600 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61  handle} {BLOB ha
33610 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ndles}.**.** An 
33620 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
33630 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
33640 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20  ts an open BLOB 
33650 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  on which.** [sql
33660 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
33670 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
33680 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65  B I/O] can be pe
33690 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a  rformed..** ^Obj
336a0 65 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70  ects of this typ
336b0 65 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79  e are created by
336c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
336d0 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65  pen()].** and de
336e0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
336f0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
33700 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  ]..** ^The [sqli
33710 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
33720 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
33730 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65  ob_write()] inte
33740 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65  rfaces.** can be
33750 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72   used to read or
33760 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62   write small sub
33770 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  sections of the 
33780 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  BLOB..** ^The [s
33790 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
337a0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  s()] interface r
337b0 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
337c0 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62  of the BLOB in b
337d0 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ytes..*/.typedef
337e0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
337f0 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f  blob sqlite3_blo
33800 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  b;../*.** CAPI3R
33810 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20  EF: Open A BLOB 
33820 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20  For Incremental 
33830 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  I/O.**.** ^(This
33840 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e   interfaces open
33850 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s a [BLOB handle
33860 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68   | handle] to th
33870 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a  e BLOB located.*
33880 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63  * in row iRow, c
33890 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74  olumn zColumn, t
338a0 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64  able zTable in d
338b0 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20  atabase zDb;.** 
338c0 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
338d0 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68  the same BLOB th
338e0 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65  at would be sele
338f0 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c  cted by:.**.** <
33900 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45  pre>.**     SELE
33910 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20  CT zColumn FROM 
33920 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45  zDb.zTable WHERE
33930 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b   [rowid] = iRow;
33940 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a  .** </pre>)^.**.
33950 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73  ** ^If the flags
33960 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
33970 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
33980 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
33990 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20  for read.** and 
339a0 77 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49  write access. ^I
339b0 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68  f it is zero, th
339c0 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64  e BLOB is opened
339d0 20 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73   for read access
339e0 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20  ..** ^It is not 
339f0 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
33a00 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
33a10 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64  s part of an ind
33a20 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a  ex or primary .*
33a30 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e  * key for writin
33a40 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20  g. ^If [foreign 
33a50 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
33a60 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74   are enabled, it
33a70 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73   is .** not poss
33a80 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
33a90 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
33aa0 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b  rt of a [child k
33ab0 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  ey] for writing.
33ac0 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
33ad0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  t the database n
33ae0 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66  ame is not the f
33af0 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e  ilename that con
33b00 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74  tains.** the dat
33b10 61 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72  abase but rather
33b20 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61   the symbolic na
33b30 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
33b40 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61  se that.** appea
33b50 72 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20  rs after the AS 
33b60 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65  keyword when the
33b70 20 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e   database is con
33b80 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54  nected using [AT
33b90 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74  TACH]..** ^For t
33ba0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
33bb0 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62   file, the datab
33bc0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69  ase name is "mai
33bd0 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50  n"..** ^For TEMP
33be0 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74   tables, the dat
33bf0 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74  abase name is "t
33c00 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  emp"..**.** ^(On
33c10 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
33c20 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
33c30 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42  d and the new [B
33c40 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77  LOB handle] is w
33c50 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70  ritten.** to *pp
33c60 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20  Blob. Otherwise 
33c70 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
33c80 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
33c90 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a  *ppBlob is set.*
33ca0 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70  * to be a null p
33cb0 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68  ointer.)^.** ^Th
33cc0 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73  is function sets
33cd0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33ce0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72  onnection] error
33cf0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
33d00 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20  e.** accessible 
33d10 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
33d20 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  code()] and [sql
33d30 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61  ite3_errmsg()] a
33d40 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75  nd related.** fu
33d50 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74  nctions. ^Note t
33d60 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20  hat the *ppBlob 
33d70 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61  variable is alwa
33d80 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69  ys initialized i
33d90 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20  n a.** way that 
33da0 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f  makes it safe to
33db0 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
33dc0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f  _blob_close()] o
33dd0 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67  n *ppBlob.** reg
33de0 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
33df0 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
33e00 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  e of this routin
33e10 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  e..**.** ^(If th
33e20 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f  e row that a BLO
33e30 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20  B handle points 
33e40 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62  to is modified b
33e50 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  y an.** [UPDATE]
33e60 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62  , [DELETE], or b
33e70 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20  y [ON CONFLICT] 
33e80 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20  side-effects.** 
33e90 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61  then the BLOB ha
33ea0 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61  ndle is marked a
33eb0 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20  s "expired"..** 
33ec0 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20  This is true if 
33ed0 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  any column of th
33ee0 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64  e row is changed
33ef0 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a  , even a column.
33f00 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68  ** other than th
33f10 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68  e one the BLOB h
33f20 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e  andle is open on
33f30 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .)^.** ^Calls to
33f40 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
33f50 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
33f60 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
33f70 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72  ] for.** a expir
33f80 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66  ed BLOB handle f
33f90 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75  ail with an retu
33fa0 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
33fb0 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28  TE_ABORT]..** ^(
33fc0 43 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20  Changes written 
33fd0 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f  into a BLOB prio
33fe0 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78  r to the BLOB ex
33ff0 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a  piring are not.*
34000 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  * rolled back by
34010 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20   the expiration 
34020 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75  of the BLOB.  Su
34030 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ch changes will 
34040 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f  eventually.** co
34050 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e  mmit if the tran
34060 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65  saction continue
34070 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  s to completion.
34080 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68  )^.**.** ^Use th
34090 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
340a0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
340b0 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ce to determine 
340c0 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74  the size of.** t
340d0 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20  he opened blob. 
340e0 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20   ^The size of a 
340f0 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20  blob may not be 
34100 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a  changed by this.
34110 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55  ** interface.  U
34120 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20  se the [UPDATE] 
34130 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63  SQL command to c
34140 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
34150 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a  f a.** blob..**.
34160 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
34170 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
34180 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
34190 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
341a0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
341b0 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
341c0 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
341d0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
341e0 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
341f0 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
34200 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
34210 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
34220 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
34230 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
34240 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
34250 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
34260 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
34270 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
34280 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
34290 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
342a0 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
342b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
342c0 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69  b_close()]..*/.i
342d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
342e0 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  open(.  sqlite3*
342f0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
34300 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  zDb,.  const cha
34310 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e  r *zTable,.  con
34320 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
34330 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ,.  sqlite3_int6
34340 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c  4 iRow,.  int fl
34350 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62  ags,.  sqlite3_b
34360 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a  lob **ppBlob.);.
34370 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34380 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
34390 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  ndle.**.** ^Clos
343a0 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  es an open [BLOB
343b0 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
343c0 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20  ^Closing a BLOB 
343d0 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
343e0 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
343f0 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
34400 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
34410 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
34420 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
34430 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
34440 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
34450 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
34460 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
34470 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79  ode]..** ^If any
34480 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
34490 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
344a0 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
344b0 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
344c0 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
344d0 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
344e0 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
344f0 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  ^(Closing the BL
34500 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
34510 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
34520 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
34530 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
34540 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
34550 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
34560 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
34570 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
34580 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65  s closed.  Any e
34590 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
345a0 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
345b0 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
345c0 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
345d0 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a  turn value.)^.**
345e0 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69  .** ^(The BLOB i
345f0 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
34600 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
34610 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
34620 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
34630 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
34640 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
34650 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  ed.)^.**.** ^Cal
34660 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
34670 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f  e with a null po
34680 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77  inter (such as w
34690 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
346a0 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20  .** by a failed 
346b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
346c0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69  _blob_open()]) i
346d0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
346e0 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
346f0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
34700 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
34710 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34720 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
34730 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  Of An Open BLOB.
34740 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74  **.** ^Returns t
34750 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
34760 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
34770 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
34780 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
34790 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61   opened [BLOB ha
347a0 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c  ndle] in its onl
347b0 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  y argument.  ^Th
347c0 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c  e.** incremental
347d0 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e   blob I/O routin
347e0 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64  es can only read
347f0 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20   or overwriting 
34800 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62  existing.** blob
34810 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63   content; they c
34820 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
34830 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e   size of a blob.
34840 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
34850 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
34860 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
34870 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
34880 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
34890 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
348a0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
348b0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
348c0 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
348d0 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
348e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
348f0 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
34900 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
34910 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
34920 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
34930 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
34940 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
34950 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
34960 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ior..*/.int sqli
34970 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
34980 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
34990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
349a0 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
349b0 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
349c0 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ally.**.** ^(Thi
349d0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
349e0 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
349f0 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  from an open [BL
34a00 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  OB handle] into 
34a10 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
34a20 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62  lied buffer. N b
34a30 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
34a40 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
34a50 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68  fer Z.** from th
34a60 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
34a70 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
34a80 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a  iOffset.)^.**.**
34a90 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
34aa0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
34ab0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
34ac0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
34ad0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
34ae0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
34af0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
34b00 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20  read.  ^If N or 
34b10 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
34b20 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
34b30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
34b40 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
34b50 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
34b60 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68   ^The size of th
34b70 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
34b80 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
34b90 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
34ba0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
34bb0 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
34bc0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
34bd0 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
34be0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74  e..**.** ^An att
34bf0 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f  empt to read fro
34c00 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  m an expired [BL
34c10 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
34c20 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
34c30 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
34c40 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
34c50 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
34c60 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
34c70 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
34c80 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
34c90 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
34ca0 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
34cb0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
34cc0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
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 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34e00 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
34e10 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  write()]..*/.int
34e20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
34e30 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
34e40 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
34e50 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
34e60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34e70 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
34e80 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
34e90 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntally.**.** ^Th
34ea0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
34eb0 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
34ec0 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
34ed0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
34ee0 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
34ef0 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e  pplied buffer. ^
34f00 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
34f10 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
34f20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
34f30 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
34f40 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
34f50 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
34f60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42  **.** ^If the [B
34f70 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
34f80 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
34f90 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
34fa0 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
34fb0 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
34fc0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
34fd0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
34fe0 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
34ff0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
35000 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
35010 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
35020 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
35030 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79   may only modify
35040 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
35050 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73   the BLOB; it is
35060 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
35070 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65   to increase the
35080 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20   size of a BLOB 
35090 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a  using this API..
350a0 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f  ** ^If offset iO
350b0 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
350c0 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
350d0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
350e0 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
350f0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
35100 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
35110 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20  s written.  ^If 
35120 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
35130 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
35140 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
35150 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
35160 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65   written..** The
35170 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
35180 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  B (and hence the
35190 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
351a0 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
351b0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
351c0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
351d0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
351e0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
351f0 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
35200 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65  to write to an e
35210 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
35220 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
35230 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
35240 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
35250 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20  T].  ^Writes to 
35260 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63  the BLOB that oc
35270 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65  curred.** before
35280 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
35290 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e  e] expired are n
352a0 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ot rolled back b
352b0 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74  y the.** expirat
352c0 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c  ion of the handl
352d0 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  e, though of cou
352e0 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65  rse those change
352f0 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20  s might.** have 
35300 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e  been overwritten
35310 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
35320 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74  t that expired t
35330 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a  he BLOB handle.*
35340 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e  * or by other in
35350 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d  dependent statem
35360 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ents..**.** ^(On
35370 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
35380 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72  3_blob_write() r
35390 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
353a0 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
353b0 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  an  [error code]
353c0 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
353d0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
353e0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
353f0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
35400 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
35410 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
35420 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
35430 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
35440 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
35450 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
35460 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
35470 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
35480 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
35490 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
354a0 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
354b0 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
354c0 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
354d0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
354e0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
354f0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
35500 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
35510 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
35520 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
35530 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ad()]..*/.int sq
35540 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
35550 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
35560 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
35570 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
35580 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
35590 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
355a0 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
355b0 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
355c0 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
355d0 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
355e0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
355f0 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
35600 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
35610 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
35620 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
35630 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c  ystem.  Most SQL
35640 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ite builds come 
35650 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
35660 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
35670 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
35680 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
35690 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
356a0 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
356b0 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
356c0 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
356d0 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
356e0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
356f0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
35700 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rovided..**.** ^
35710 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
35720 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
35730 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
35740 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
35750 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  n its name..** ^
35760 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
35770 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61  ensitive..** ^Na
35780 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
35790 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
357a0 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  rings..** ^If th
357b0 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
357c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
357d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
357e0 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20  ^If zVfsName is 
357f0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
35800 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74  fault VFS is ret
35810 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65  urned..**.** ^Ne
35820 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
35830 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
35840 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
35850 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77  ()..** ^Each new
35860 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
35870 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
35880 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
35890 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  g is set..** ^Th
358a0 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62  e same VFS can b
358b0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
358c0 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
358d0 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e  out injury..** ^
358e0 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74  To make an exist
358f0 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65  ing VFS into the
35900 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65   default VFS, re
35910 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a  gister it again.
35920 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65  ** with the make
35930 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20  Dflt flag set.  
35940 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74  If two different
35950 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a   VFSes with the.
35960 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  ** same name are
35970 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65   registered, the
35980 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
35990 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a  efined.  If a.**
359a0 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
359b0 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74  ed with a name t
359c0 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  hat is NULL or a
359d0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a  n empty string,.
359e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
359f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
35a00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69  d..**.** ^Unregi
35a10 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20  ster a VFS with 
35a20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  the sqlite3_vfs_
35a30 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74  unregister() int
35a40 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20  erface..** ^(If 
35a50 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
35a60 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c  is unregistered,
35a70 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20   another VFS is 
35a80 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65  chosen as.** the
35a90 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63   default.  The c
35aa0 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65  hoice for the ne
35ab0 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61  w VFS is arbitra
35ac0 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33  ry.)^.*/.sqlite3
35ad0 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
35ae0 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
35af0 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
35b00 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
35b10 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
35b20 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
35b30 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
35b40 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
35b50 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
35b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
35b70 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  utexes.**.** The
35b80 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
35b90 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
35ba0 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73   for thread.** s
35bb0 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20  ynchronization. 
35bc0 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20  Though they are 
35bd0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74  intended for int
35be0 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
35bf0 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61  SQLite, code tha
35c00 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
35c10 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72  SQLite is.** per
35c20 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e  mitted to use an
35c30 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
35c40 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  nes..**.** The S
35c50 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
35c60 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69  e contains multi
35c70 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
35c80 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  ons.** of these 
35c90 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20  mutex routines. 
35ca0 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   An appropriate 
35cb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
35cc0 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75  * is selected au
35cd0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63  tomatically at c
35ce0 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28  ompile-time.  ^(
35cf0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
35d00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35d10 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
35d20 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
35d30 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
35d40 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
35d50 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
35d60 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
35d70 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
35d80 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
35d90 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
35da0 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
35db0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
35dc0 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  ^The SQLITE_MUTE
35dd0 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
35de0 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
35df0 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68  f routines.** th
35e00 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20  at does no real 
35e10 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61  locking and is a
35e20 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
35e30 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c  se in.** a singl
35e40 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
35e50 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51  cation.  ^The SQ
35e60 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a  LITE_MUTEX_OS2,.
35e70 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
35e80 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c  PTHREAD, and SQL
35e90 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d  ITE_MUTEX_W32 im
35ea0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
35eb0 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65   are appropriate
35ec0 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32   for use on OS/2
35ed0 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64  , Unix, and Wind
35ee0 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ows..**.** ^(If 
35ef0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
35f00 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
35f10 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
35f20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
35f30 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
35f40 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
35f50 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
35f60 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
35f70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35f80 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
35f90 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
35fa0 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
35fb0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
35fc0 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
35fd0 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
35fe0 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
35ff0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
36000 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
36010 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
36020 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
36030 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
36040 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
36050 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
36060 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
36070 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
36080 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
36090 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
360a0 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
360b0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
360c0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
360d0 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
360e0 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
360f0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
36100 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75   it. ^If it retu
36110 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74  rns NULL.** that
36120 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75   means that a mu
36130 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  tex could not be
36140 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51   allocated.  ^SQ
36150 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
36160 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
36170 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
36180 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65  r.  ^(The argume
36190 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
361a0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
361b0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
361c0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
361d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
361e0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
361f0 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
36200 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
36210 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
36220 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
36230 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
36240 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
36250 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
36260 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36270 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
36280 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
36290 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
362a0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
362b0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
362c0 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  U.** <li>  SQLIT
362d0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
362e0 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  RU2.** </ul>)^.*
362f0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
36300 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53  two constants (S
36310 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
36320 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
36330 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20  X_RECURSIVE).** 
36340 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75  cause sqlite3_mu
36350 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63  tex_alloc() to c
36360 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d  reate.** a new m
36370 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20  utex.  ^The new 
36380 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
36390 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
363a0 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
363b0 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
363c0 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
363d0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
363e0 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
363f0 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
36400 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
36410 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61  s not need to ma
36420 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e  ke a distinction
36430 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
36440 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
36450 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  VE and SQLITE_MU
36460 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64  TEX_FAST if it d
36470 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
36480 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  to.  ^SQLite wil
36490 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
364a0 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
364b0 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
364c0 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
364d0 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66  ds one.  ^If a f
364e0 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
364f0 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
36500 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
36510 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
36520 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
36530 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
36540 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
36550 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
36560 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
36570 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
36580 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68  ..**.** ^The oth
36590 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d  er allowed param
365a0 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33  eters to sqlite3
365b0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28  _mutex_alloc() (
365c0 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a  anything other.*
365d0 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55  * than SQLITE_MU
365e0 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c  TEX_FAST and SQL
365f0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
36600 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72 6e  IVE) each return
36610 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
36620 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
36630 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53  sting mutex.  ^S
36640 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  ix static mutexe
36650 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79  s are.** used by
36660 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72   the current ver
36670 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20  sion of SQLite. 
36680 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
36690 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61   of SQLite.** ma
366a0 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
366b0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
366c0 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
366d0 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61   are for interna
366e0 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
366f0 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  te only.  Applic
36700 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
36710 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73  SQLite mutexes s
36720 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c  hould.** use onl
36730 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  y the dynamic mu
36740 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62  texes returned b
36750 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  y SQLITE_MUTEX_F
36760 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  AST or.** SQLITE
36770 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
36780 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
36790 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
367a0 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
367b0 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
367c0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
367d0 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
367e0 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
367f0 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
36800 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
36810 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
36820 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
36830 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20  ery call.  ^But 
36840 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a  for the static.*
36850 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74  * mutex types, t
36860 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73  he same mutex is
36870 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65   returned on eve
36880 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73  ry call that has
36890 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70  .** the same typ
368a0 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  e number..**.** 
368b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
368c0 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
368d0 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
368e0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
368f0 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
36900 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20  mutex.  ^SQLite 
36910 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65  is careful to de
36920 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a  allocate every.*
36930 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  * dynamic mutex 
36940 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65  that it allocate
36950 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20  s.  The dynamic 
36960 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
36970 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68   be in.** use wh
36980 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
36990 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
369a0 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
369b0 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
369c0 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
369d0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
369e0 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76  or.  ^SQLite nev
369f0 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
36a00 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
36a10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36a20 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
36a30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
36a40 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
36a50 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
36a60 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
36a70 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68    ^If another th
36a80 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
36a90 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
36aa0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
36ab0 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
36ac0 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
36ad0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
36ae0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
36af0 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20  ITE_BUSY.  ^The 
36b00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36b10 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
36b20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
36b30 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73  ].** upon succes
36b40 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d  sful entry.  ^(M
36b50 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75  utexes created u
36b60 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  sing.** SQLITE_M
36b70 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63  UTEX_RECURSIVE c
36b80 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75  an be entered mu
36b90 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20  ltiple times by 
36ba0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
36bb0 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65  .** In such case
36bc0 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
36bd0 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
36be0 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
36bf0 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
36c00 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
36c10 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e   can enter.)^  ^
36c20 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72  (If the same thr
36c30 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74  ead tries to ent
36c40 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  er any other.** 
36c50 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f  kind of mutex mo
36c60 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68  re than once, th
36c70 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
36c80 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69  defined..** SQLi
36c90 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
36ca0 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
36cb0 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
36cc0 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
36cd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65  .)^.**.** ^(Some
36ce0 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
36cf0 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
36d00 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
36d10 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
36d20 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
36d30 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
36d40 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
36d50 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
36d60 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
36d70 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
36d80 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
36d90 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
36da0 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73  e only ever uses
36db0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
36dc0 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70  x_try() as an op
36dd0 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68  timization so th
36de0 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  is is acceptable
36df0 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a   behavior.)^.**.
36e00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36e10 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
36e20 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
36e30 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
36e40 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
36e50 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
36e60 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62  hread.   ^(The b
36e70 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
36e80 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
36e90 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
36ea0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
36eb0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
36ec0 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
36ed0 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
36ee0 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69  ated.  SQLite wi
36ef0 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65  ll.** never do e
36f00 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ither.)^.**.** ^
36f10 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
36f20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
36f30 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65  _enter(), sqlite
36f40 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f  3_mutex_try(), o
36f50 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  r.** sqlite3_mut
36f60 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20  ex_leave() is a 
36f70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
36f80 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75  en all three rou
36f90 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20  tines.** behave 
36fa0 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  as no-ops..**.**
36fb0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
36fc0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
36fd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d  ] and [sqlite3_m
36fe0 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e  utex_notheld()].
36ff0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
37000 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
37010 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
37020 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
37030 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
37040 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
37050 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
37060 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
37070 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
37080 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
37090 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
370a0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
370b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
370c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
370d0 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20  : Mutex Methods 
370e0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
370f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
37100 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e   structure defin
37110 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c  es the low-level
37120 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
37130 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e  d to allocate an
37140 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a  d use mutexes..*
37150 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68  *.** Usually, th
37160 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
37170 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37180 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69  provided by SQLi
37190 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63  te are.** suffic
371a0 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68  ient, however th
371b0 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f  e user has the o
371c0 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74  ption of substit
371d0 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a  uting a custom.*
371e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
371f0 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64   for specialized
37200 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20   deployments or 
37210 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63  systems for whic
37220 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73  h SQLite.** does
37230 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73   not provide a s
37240 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
37250 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20  tation. In this 
37260 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a  case, the user.*
37270 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f  * creates and po
37280 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61  pulates an insta
37290 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
372a0 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a  cture to pass.**
372b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
372c0 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20  ig() along with 
372d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
372e0 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
372f0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ..** Additionall
37300 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  y, an instance o
37310 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
37320 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
37330 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72  an.** output var
37340 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79  iable when query
37350 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66  ing the system f
37360 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  or the current m
37370 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
37380 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68  tation, using th
37390 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
373a0 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f  _GETMUTEX] optio
373b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d  n..**.** ^The xM
373c0 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  utexInit method 
373d0 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
373e0 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
373f0 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
37400 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61  of system initia
37410 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20  lization by the 
37420 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
37430 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ze() function..*
37440 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69  * ^The xMutexIni
37450 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  t routine is cal
37460 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 61  le by SQLite exa
37470 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61  ctly once for ea
37480 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20  ch.** effective 
37490 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
374a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a  _initialize()]..
374b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  **.** ^The xMute
374c0 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69  xEnd method defi
374d0 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
374e0 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
374f0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
37500 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62  ystem shutdown b
37510 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68  y the sqlite3_sh
37520 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f  utdown() functio
37530 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  n. The.** implem
37540 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73  entation of this
37550 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63   method is expec
37560 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61  ted to release a
37570 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a  ll outstanding.*
37580 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61  * resources obta
37590 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65  ined by the mute
375a0 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d  x methods implem
375b0 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69  entation, especi
375c0 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62  ally.** those ob
375d0 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d  tained by the xM
375e0 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e  utexInit method.
375f0 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64    ^The xMutexEnd
37600 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
37610 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  is invoked exact
37620 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
37630 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
37640 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
37650 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69  *.** ^(The remai
37660 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f  ning seven metho
37670 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  ds defined by th
37680 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d  is structure (xM
37690 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d  utexAlloc,.** xM
376a0 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78  utexFree, xMutex
376b0 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79  Enter, xMutexTry
376c0 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78  , xMutexLeave, x
376d0 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a  MutexHeld and.**
376e0 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20   xMutexNotheld) 
376f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f  implement the fo
37700 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
37710 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79  es (respectively
37720 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ):.**.** <ul>.**
37730 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
37740 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
37750 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
37760 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
37770 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  _free()] </li>.*
37780 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
37790 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
377a0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
377b0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
377c0 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  x_try()] </li>.*
377d0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
377e0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
377f0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
37800 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
37810 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a  x_held()] </li>.
37820 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
37830 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
37840 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  d()] </li>.** </
37850 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
37860 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
37870 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c  is that the publ
37880 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66  ic sqlite3_XXX f
37890 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61  unctions enumera
378a0 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c  ted.** above sil
378b0 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79  ently ignore any
378c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61   invocations tha
378d0 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f  t pass a NULL po
378e0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  inter instead.**
378f0 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
37900 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d  x handle. The im
37910 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
37920 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66   the methods def
37930 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  ined.** by this 
37940 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f  structure are no
37950 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61  t required to ha
37960 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20  ndle this case, 
37970 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f  the results.** o
37980 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c  f passing a NULL
37990 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
379a0 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
379b0 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64  x handle are und
379c0 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20  efined.** (i.e. 
379d0 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  it is acceptable
379e0 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69   to provide an i
379f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
37a00 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a  at segfaults if.
37a10 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20  ** it is passed 
37a20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e  a NULL pointer).
37a30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
37a40 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d  xInit() method m
37a50 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
37a60 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20  e.  ^It must be 
37a70 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69  harmless to.** i
37a80 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74  nvoke xMutexInit
37a90 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73  () mutiple times
37aa0 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
37ab0 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74   process and wit
37ac0 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e  hout.** interven
37ad0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75  ing calls to xMu
37ae0 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e  texEnd().  Secon
37af0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
37b00 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75   calls to.** xMu
37b10 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62  texInit() must b
37b20 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  e no-ops..**.** 
37b30 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75  ^xMutexInit() mu
37b40 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
37b50 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
37b60 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61  ion ([sqlite3_ma
37b70 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69  lloc()].** and i
37b80 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20  ts associates). 
37b90 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75   ^Similarly, xMu
37ba0 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20  texAlloc() must 
37bb0 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
37bc0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
37bd0 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63  ion for a static
37be0 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65   mutex.  ^Howeve
37bf0 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20  r xMutexAlloc() 
37c00 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a  may use SQLite.*
37c10 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
37c20 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f  ion for a fast o
37c30 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  r recursive mute
37c40 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  x..**.** ^SQLite
37c50 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
37c60 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74   xMutexEnd() met
37c70 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  hod when [sqlite
37c80 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73  3_shutdown()] is
37c90 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20  .** called, but 
37ca0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f  only if the prio
37cb0 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78  r call to xMutex
37cc0 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51  Init returned SQ
37cd0 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78  LITE_OK..** If x
37ce0 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20  MutexInit fails 
37cf0 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69  in any way, it i
37d00 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c  s expected to cl
37d10 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73  ean up after its
37d20 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  elf.** prior to 
37d30 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79  returning..*/.ty
37d40 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
37d50 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
37d60 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
37d70 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
37d80 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
37d90 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
37da0 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
37db0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
37dc0 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
37dd0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
37de0 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
37df0 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
37e00 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
37e10 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
37e20 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
37e30 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
37e40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
37e50 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
37e60 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
37e70 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
37e80 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
37e90 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
37ea0 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
37eb0 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
37ec0 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
37ed0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
37ee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37ef0 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
37f00 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
37f10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
37f20 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
37f30 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
37f40 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
37f50 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
37f60 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
37f70 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
37f80 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c  ments.  ^The SQL
37f90 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
37fa0 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
37fb0 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
37fc0 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
37fd0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
37fe0 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
37ff0 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
38000 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
38010 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72   ^The SQLite cor
38020 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
38030 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
38040 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
38050 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
38060 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
38070 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
38080 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72  UG flag.  ^Exter
38090 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
380a0 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
380b0 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
380c0 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
380d0 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
380e0 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
380f0 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
38100 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
38110 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
38120 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
38130 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
38140 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
38150 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
38160 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
38170 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
38180 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
38190 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  g thread..**.** 
381a0 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
381b0 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
381c0 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
381d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
381e0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
381f0 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
38200 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  . If the impleme
38210 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
38220 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
38230 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
38240 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
38250 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
38260 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
38270 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20   that always.** 
38280 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
38290 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
382a0 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73   get spurious as
382b0 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
382c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
382d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
382e0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
382f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
38300 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
38310 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
38320 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73  turn 1.   This s
38330 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74  eems counter-int
38340 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20  uitive since.** 
38350 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65  clearly the mute
38360 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64  x cannot be held
38370 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
38380 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a  exist.  But the.
38390 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68  ** the reason th
383a0 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74  e mutex does not
383b0 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73   exist is becaus
383c0 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e  e the build is n
383d0 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65  ot.** using mute
383e0 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20  xes.  And we do 
383f0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73  not want the ass
38400 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67  ert() containing
38410 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20   the.** call to 
38420 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
38430 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f  ld() to fail, so
38440 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
38450 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70  rn is.** the app
38460 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74  ropriate thing t
38470 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  o do.  ^The sqli
38480 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
38490 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
384a0 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
384b0 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
384c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
384d0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42  .*/.#ifndef NDEB
384e0 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  UG.int sqlite3_m
384f0 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
38500 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
38510 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
38520 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
38530 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  ex*);.#endif../*
38540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
38550 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20  tex Types.**.** 
38560 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  The [sqlite3_mut
38570 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65  ex_alloc()] inte
38580 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69  rface takes a si
38590 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
385a0 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66   which is one of
385b0 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
385c0 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
385d0 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69  The set of stati
385e0 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68  c mutexes may ch
385f0 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51  ange from one SQ
38600 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20  Lite release to 
38610 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
38620 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
38630 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69  override the bui
38640 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69  lt-in mutex logi
38650 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65  c must be.** pre
38660 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f  pared to accommo
38670 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  date additional 
38680 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a  static mutexes..
38690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
386a0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20  E_MUTEX_FAST    
386b0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
386c0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
386d0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
386e0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
386f0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
38700 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69  ASTER    2.#defi
38710 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
38720 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20  STATIC_MEM      
38730 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   3  /* sqlite3_m
38740 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69  alloc() */.#defi
38750 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
38760 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20  STATIC_MEM2     
38770 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20   4  /* NOT USED 
38780 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38790 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f  E_MUTEX_STATIC_O
387a0 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73  PEN      4  /* s
387b0 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28  qlite3BtreeOpen(
387c0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
387d0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
387e0 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
387f0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
38800 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
38810 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
38820 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
38830 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
38840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
38850 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
38860 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72  U2      7  /* lr
38870 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a  u page list */..
38880 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38890 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74  Retrieve the mut
388a0 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  ex for a databas
388b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e connection.**.
388c0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
388d0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
388e0 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65  nter the [sqlite
388f0 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20  3_mutex] object 
38900 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69  that .** seriali
38910 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68  zes access to th
38920 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38930 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e  ec