/ Hex Artifact Content
Login

Artifact b77b914f5f4c301ca00b2fc0fe253240ec177503:


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 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
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: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
8580: 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ll guarantee tha
8590: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
85a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
85b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
85c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
85d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
85e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
85f0: 61 74 68 6e 61 6d 65 28 29 2e 20 20 5e 53 51 4c  athname().  ^SQL
8600: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
8610: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
8620: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
8630: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
8640: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
8650: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
8660: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
8670: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
8680: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
8690: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
86a0: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
86b0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
86c0: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
86d0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
86e0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
86f0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
8700: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
8710: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
8720: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
8730: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
8740: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
8750: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
8760: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
8770: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
8780: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
8790: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
87a0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
87b0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
87c0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
87d0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
87e0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
87f0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8800: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
8810: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
8820: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
8830: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
8840: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
8850: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
8860: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
8870: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
8880: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
8890: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
88a0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
88b0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
88c0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
88d0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
88e0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
88f0: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
8900: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
8910: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
8920: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
8930: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
8940: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
8950: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
8960: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
8970: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
8980: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
8990: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
89a0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
89b0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
89c0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
89d0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
89e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
89f0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
8a00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
8a10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8a20: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8a30: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
8a40: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8a50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8a60: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
8a70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
8a80: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
8a90: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8aa0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
8ab0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8ac0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
8ad0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8ae0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
8af0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8b00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
8b10: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
8b20: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
8b30: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
8b40: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
8b50: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
8b60: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
8b70: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
8b80: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
8b90: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
8ba0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
8bb0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
8bc0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
8bd0: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
8be0: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
8bf0: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
8c00: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
8c10: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
8c20: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
8c30: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
8c40: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
8c50: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
8c60: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
8c70: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
8c80: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
8c90: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
8ca0: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
8cb0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
8cc0: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
8cd0: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
8ce0: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
8cf0: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
8d00: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
8d10: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
8d20: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
8d30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
8d40: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
8d50: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8d60: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8d70: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
8d80: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8d90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8da0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
8db0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
8dc0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
8dd0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
8de0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8df0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
8e00: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
8e10: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
8e20: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8e30: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
8e40: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8e50: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8e60: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8e70: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
8e80: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
8e90: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
8ea0: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
8eb0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
8ec0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
8ed0: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
8ee0: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
8ef0: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
8f00: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
8f10: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
8f20: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
8f30: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
8f40: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
8f50: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
8f60: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
8f70: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
8f80: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
8f90: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
8fa0: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
8fb0: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
8fc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
8fd0: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
8fe0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
8ff0: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
9000: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
9010: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
9020: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
9030: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
9040: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
9050: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
9060: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
9070: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
9080: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
9090: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
90a0: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
90b0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
90c0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
90d0: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
90e0: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
90f0: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
9100: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
9110: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
9120: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
9130: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
9140: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
9150: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
9160: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
9170: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
9180: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
9190: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
91a0: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
91b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
91c0: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
91d0: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
91e0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
91f0: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
9200: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
9210: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
9220: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
9230: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
9240: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
9250: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
9260: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
9270: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
9280: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
9290: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
92a0: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
92b0: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
92c0: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n call..**.** ^T
92d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
92e0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
92f0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
9300: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
9310: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
9320: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
9330: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
9340: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
9350: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
9360: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
9370: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
9380: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
9390: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
93a0: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
93b0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
93c0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
93d0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
93e0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
93f0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
9400: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
9410: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
9420: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
9430: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
9440: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
9450: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
9460: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
9470: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
9480: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
9490: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
94a0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
94b0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
94c0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
94d0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
94e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
94f0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
9500: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
9510: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
9520: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
9530: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
9540: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
9550: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
9560: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
9570: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
9580: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
9590: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
95a0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
95b0: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
95c0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
95d0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
95e0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
95f0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
9600: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
9610: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
9620: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
9630: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
9640: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
9650: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
9660: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
9670: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
9680: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
9690: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
96a0: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
96b0: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
96c0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
96d0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
96e0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
96f0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
9700: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
9710: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
9720: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
9730: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
9740: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
9750: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
9760: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
9770: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
9780: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
9790: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
97a0: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
97b0: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
97c0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
97d0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
97e0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
97f0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
9800: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
9810: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
9820: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
9830: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
9840: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
9850: 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36 34  multipled by 864
9860: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
9870: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
9880: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
9890: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
98a0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
98b0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
98c0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
98d0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
98e0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
98f0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
9900: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
9910: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
9920: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
9930: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
9940: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
9950: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
9960: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
9970: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
9980: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
9990: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
99a0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
99b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
99c0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
99d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
99e0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
99f0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
9a00: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
9a10: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
9a20: 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69 6e  ently 2) */.  in
9a30: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
9a40: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
9a50: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
9a60: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
9a70: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
9a80: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
9a90: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
9aa0: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
9ab0: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
9ac0: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
9ad0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
9ae0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
9af0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
9b00: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
9b10: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
9b20: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
9b30: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
9b40: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
9b50: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
9b60: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
9b70: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
9b80: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9b90: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
9ba0: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
9bb0: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
9bc0: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
9bd0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
9be0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9bf0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9c00: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
9c10: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
9c20: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
9c30: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9c40: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
9c50: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
9c60: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
9c70: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
9c80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9c90: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
9ca0: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
9cb0: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
9cc0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9cd0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
9ce0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
9cf0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
9d00: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
9d10: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
9d20: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
9d30: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
9d40: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
9d50: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
9d60: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
9d70: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
9d80: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
9d90: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
9da0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9db0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
9dc0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
9dd0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
9de0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
9df0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
9e00: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
9e10: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
9e20: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
9e30: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
9e40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9e50: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
9e60: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
9e70: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
9e80: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
9e90: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
9ea0: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
9eb0: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
9ec0: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
9ed0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
9ee0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
9ef0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
9f00: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
9f10: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
9f20: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
9f30: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9f40: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
9f50: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
9f60: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
9f70: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
9f80: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
9f90: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
9fa0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
9fb0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
9fc0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
9fd0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
9fe0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
9ff0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a000: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
a010: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
a020: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
a030: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
a040: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
a050: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
a060: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
a070: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
a080: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
a090: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
a0a0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
a0b0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
a0c0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
a0d0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
a0e0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
a0f0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
a100: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
a110: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
a120: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
a130: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
a140: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
a150: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
a160: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
a170: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
a180: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
a190: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
a1a0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
a1b0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
a1c0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
a1d0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
a1e0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
a1f0: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
a200: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
a210: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
a220: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a230: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
a240: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
a250: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
a260: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
a270: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
a280: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
a290: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
a2a0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
a2b0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
a2c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a2d0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
a2e0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
a2f0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
a300: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
a310: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
a320: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
a330: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
a340: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
a350: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
a360: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
a370: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
a380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a390: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
a3a0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
a3b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
a3c0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
a3d0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
a3e0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
a3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a400: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
a410: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
a420: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
a430: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
a440: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
a450: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
a460: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
a470: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
a480: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
a490: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
a4a0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
a4b0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
a4c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
a4d0: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
a4e0: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
a4f0: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
a500: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
a510: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
a520: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
a530: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
a540: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
a550: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
a560: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
a570: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
a580: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
a590: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
a5a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
a5b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
a5c0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
a5d0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
a5e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
a5f0: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
a600: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
a610: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
a620: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
a630: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
a640: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
a650: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
a660: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
a670: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
a680: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
a690: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
a6a0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
a6b0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
a6c0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
a6d0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
a6e0: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
a6f0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
a700: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
a710: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
a720: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
a730: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
a740: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
a750: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
a760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
a770: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
a780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
a790: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
a7a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a7b0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
a7c0: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
a7d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
a7e0: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
a7f0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
a800: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
a810: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
a820: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
a830: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
a840: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
a850: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
a860: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
a870: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
a880: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
a890: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
a8a0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
a8b0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
a8c0: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
a8d0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
a8e0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
a8f0: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
a900: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
a910: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
a920: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
a930: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
a940: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
a950: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
a960: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
a970: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
a980: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
a990: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
a9a0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
a9b0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
a9c0: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
a9d0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
a9e0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
a9f0: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
aa00: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
aa10: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
aa20: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
aa30: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
aa40: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
aa50: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
aa60: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
aa70: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
aa80: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
aa90: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
aaa0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
aab0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
aac0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
aad0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
aae0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
aaf0: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
ab00: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
ab10: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
ab20: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
ab30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ab40: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
ab50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
ab60: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
ab70: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
ab80: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
ab90: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
aba0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
abb0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
abc0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
abd0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
abe0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
abf0: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
ac00: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
ac10: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
ac20: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
ac30: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
ac40: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
ac50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
ac60: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
ac70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ac80: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
ac90: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
aca0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
acb0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
acc0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
acd0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
ace0: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
acf0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
ad00: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ad10: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
ad20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ad30: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
ad40: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
ad50: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
ad60: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
ad70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
ad80: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
ad90: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
ada0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
adb0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
adc0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
add0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
ade0: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
adf0: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
ae00: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
ae10: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
ae20: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
ae30: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
ae40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
ae50: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
ae60: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
ae70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
ae80: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
ae90: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
aea0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
aeb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
aec0: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
aed0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
aee0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
aef0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
af00: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
af10: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
af20: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
af30: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
af40: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
af50: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
af60: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
af70: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
af80: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
af90: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
afa0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
afb0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
afc0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
afd0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
afe0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
aff0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
b000: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
b010: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
b020: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
b030: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
b040: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
b050: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
b060: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
b070: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
b080: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
b090: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
b0a0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
b0b0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
b0c0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
b0d0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
b0e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
b0f0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
b100: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
b110: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
b120: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
b130: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
b140: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
b150: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
b160: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
b170: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
b180: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
b190: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
b1a0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
b1b0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
b1c0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
b1d0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
b1e0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
b1f0: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
b200: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
b210: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
b220: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
b230: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
b240: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
b250: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
b260: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
b270: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
b280: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
b290: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
b2a0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
b2b0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
b2c0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
b2d0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
b2e0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
b2f0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
b300: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
b310: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
b320: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
b330: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
b340: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
b350: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
b360: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
b370: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
b380: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
b390: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
b3a0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
b3b0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
b3c0: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
b3d0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
b3e0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
b3f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b400: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
b410: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
b420: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
b430: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
b440: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
b450: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
b460: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
b470: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
b480: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
b490: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
b4a0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
b4b0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
b4c0: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
b4d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
b4e0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
b4f0: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
b500: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
b510: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
b520: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
b530: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
b540: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
b550: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
b560: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
b570: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
b580: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
b590: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
b5a0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
b5b0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
b5c0: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
b5d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
b5e0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
b5f0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
b600: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
b610: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
b620: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
b630: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
b640: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
b650: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
b660: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
b670: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
b680: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
b690: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
b6a0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
b6b0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
b6c0: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
b6d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
b6e0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
b6f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
b700: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
b710: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
b720: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
b730: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
b740: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
b750: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
b760: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
b770: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
b780: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
b790: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
b7a0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
b7b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
b7c0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
b7d0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
b7e0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b7f0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
b800: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
b810: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
b820: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
b830: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
b840: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
b850: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
b860: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
b870: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
b880: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
b890: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
b8a0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
b8b0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
b8c0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
b8d0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
b8e0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
b8f0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
b900: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
b910: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
b920: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
b930: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
b940: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
b950: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
b960: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
b970: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
b980: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
b990: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
b9a0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
b9b0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
b9c0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
b9d0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
b9e0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
b9f0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
ba00: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
ba10: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
ba20: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ba30: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
ba40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
ba50: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
ba60: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
ba70: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
ba80: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
ba90: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
baa0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
bab0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
bac0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
bad0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
bae0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
baf0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bb00: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
bb10: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
bb20: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
bb30: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
bb40: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
bb50: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
bb60: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
bb70: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
bb80: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
bb90: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
bba0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
bbb0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bbc0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
bbd0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
bbe0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
bbf0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
bc00: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
bc10: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
bc20: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
bc30: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
bc40: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
bc50: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
bc60: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
bc70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bc80: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
bc90: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
bca0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
bcb0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
bcc0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
bcd0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
bce0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
bcf0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
bd00: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
bd10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
bd20: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
bd30: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
bd40: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
bd50: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
bd60: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
bd70: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
bd80: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
bd90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
bda0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
bdb0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
bdc0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
bdd0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
bde0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
bdf0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
be00: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
be10: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
be20: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
be30: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
be40: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
be50: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
be60: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
be70: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
be80: 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
be90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
bea0: 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
beb0: 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
bec0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
bed0: 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
bee0: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
bef0: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
bf00: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
bf10: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
bf20: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
bf30: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
bf40: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
bf50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
bf60: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
bf70: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
bf80: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
bf90: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  nections.**.** T
bfa0: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
bfb0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
bfc0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
bfd0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
bfe0: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
bff0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c000: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
c010: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
c020: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
c030: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
c040: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
c050: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
c060: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
c070: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
c080: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
c090: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20  rst argument).  
c0a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64  The.** sqlite3_d
c0b0: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
c0c0: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  face should only
c0d0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
c0e0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
c0f0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
c100: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
c110: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
c120: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
c130: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
c140: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
c150: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
c160: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
c170: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
c180: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
c190: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
c1a0: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
c1b0: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
c1c0: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
c1d0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
c1e0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
c1f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
c200: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
c210: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
c220: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
c230: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
c240: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
c250: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
c260: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
c270: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
c280: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
c290: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
c2a0: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
c2b0: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
c2c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
c2d0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
c2e0: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
c2f0: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
c300: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
c310: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
c320: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
c330: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
c340: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
c350: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
c360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
c370: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
c380: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
c390: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c3a0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
c3b0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
c3c0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
c3d0: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
c3e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c3f0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
c400: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
c410: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
c420: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
c430: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
c440: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
c450: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
c460: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
c470: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
c480: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
c490: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
c4a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c4b0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
c4c0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
c4d0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
c4e0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
c4f0: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
c500: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c510: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
c520: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
c530: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
c540: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
c550: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
c560: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
c570: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
c580: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
c590: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
c5a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c5b0: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
c5c0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
c5d0: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
c5e0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
c5f0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
c600: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
c610: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
c620: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
c630: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
c640: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
c650: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
c660: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
c670: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
c680: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
c690: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
c6a0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
c6b0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
c6c0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
c6d0: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
c6e0: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
c6f0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
c700: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
c710: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
c720: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
c730: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
c740: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
c750: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
c760: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
c770: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
c780: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
c790: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
c7a0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
c7b0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
c7c0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
c7d0: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
c7e0: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
c7f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
c800: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  oc and xFree met
c810: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
c820: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
c830: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
c840: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
c850: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
c860: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65  rary..** The xRe
c870: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73  alloc method mus
c880: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c  t work like real
c890: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73  loc() from the s
c8a0: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
c8b0: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78  y.** with the ex
c8c0: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20  ception that if 
c8d0: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
c8e0: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20  ent to xRealloc 
c8f0: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61  is zero,.** xRea
c900: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e  lloc must be a n
c910: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e  o-op - it must n
c920: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61  ot perform any a
c930: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20  llocation or.** 
c940: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e  deallocation.  ^
c950: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
c960: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
c970: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
c980: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
c990: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
c9a0: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
c9b0: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
c9c0: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63  ..** And so in c
c9d0: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e  ases where xRoun
c9e0: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72  dup always retur
c9f0: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
ca00: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  mber,.** xReallo
ca10: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78  c can perform ex
ca20: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61  actly as the sta
ca30: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65  ndard library re
ca40: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73  alloc() and.** s
ca50: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c  till be in compl
ca60: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20  iance with this 
ca70: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
ca80: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
ca90: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
caa0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
cab0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cac0: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
cad0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
cae0: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
caf0: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
cb00: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
cb10: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
cb20: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
cb30: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
cb40: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
cb50: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
cb60: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
cb70: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
cb80: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
cb90: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
cba0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
cbb0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
cbc0: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
cbd0: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
cbe0: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
cbf0: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
cc00: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
cc10: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
cc20: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
cc30: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
cc40: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
cc50: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
cc60: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
cc70: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
cc80: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
cc90: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
cca0: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
ccb0: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
ccc0: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
ccd0: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
cce0: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
ccf0: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
cd00: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
cd10: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
cd20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cd30: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
cd40: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
cd50: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
cd60: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
cd70: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
cd80: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
cd90: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
cda0: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
cdb0: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
cdc0: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
cdd0: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
cde0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
cdf0: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
ce00: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
ce10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
ce20: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
ce30: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
ce40: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
ce50: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
ce60: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
ce70: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
ce80: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
ce90: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
cea0: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
ceb0: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
cec0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
ced0: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
cee0: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
cef0: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
cf00: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
cf10: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
cf20: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
cf30: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
cf40: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
cf50: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
cf60: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
cf70: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
cf80: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
cf90: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
cfa0: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
cfb0: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
cfc0: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
cfd0: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
cfe0: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
cff0: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
d000: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
d010: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
d020: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d030: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
d040: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
d050: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
d060: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
d070: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
d080: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
d090: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
d0a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
d0b0: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
d0c0: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
d0d0: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
d0e0: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
d0f0: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
d100: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
d110: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
d120: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
d130: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
d140: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
d150: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
d160: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
d170: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
d180: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
d190: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d1a0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
d1b0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
d1c0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
d1d0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
d1e0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
d1f0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
d200: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
d210: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
d220: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
d230: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
d240: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
d250: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
d260: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
d270: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
d280: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
d290: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
d2a0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
d2b0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
d2c0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
d2d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
d2e0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
d2f0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
d300: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
d310: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
d320: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
d330: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
d340: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
d350: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
d360: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
d370: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
d380: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
d390: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
d3a0: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
d3b0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
d3c0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
d3d0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
d3e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
d3f0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
d400: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
d410: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
d420: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
d430: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
d440: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
d450: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
d460: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
d470: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
d480: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
d490: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
d4a0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
d4b0: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
d4c0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
d4d0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
d4e0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
d4f0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
d500: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
d510: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
d520: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
d530: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d540: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
d550: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
d560: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
d570: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
d580: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
d590: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
d5a0: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
d5b0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
d5c0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
d5d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d5e0: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
d5f0: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
d600: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
d610: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
d620: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
d630: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
d640: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
d650: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
d660: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
d670: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
d680: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
d690: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
d6a0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
d6b0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
d6c0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
d6d0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
d6e0: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
d6f0: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
d700: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
d710: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
d720: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
d730: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
d740: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
d750: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
d760: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
d770: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
d780: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
d790: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
d7a0: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
d7b0: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
d7c0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
d7d0: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
d7e0: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
d7f0: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
d800: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
d810: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
d820: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
d830: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
d840: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d850: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
d860: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
d870: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
d880: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d890: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
d8a0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d8b0: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
d8c0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d8d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
d8e0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
d8f0: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
d900: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
d910: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
d920: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
d930: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
d940: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
d950: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d960: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
d970: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
d980: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d990: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d9a0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
d9b0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
d9c0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
d9d0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
d9e0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
d9f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da00: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
da10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
da20: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
da30: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
da40: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
da50: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
da60: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
da70: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
da80: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
da90: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
daa0: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
dab0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
dac0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
dad0: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
dae0: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
daf0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
db00: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
db10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
db20: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
db30: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
db40: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
db50: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
db60: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
db70: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
db80: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
db90: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
dba0: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
dbb0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
dbc0: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
dbd0: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
dbe0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
dbf0: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
dc00: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
dc10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
dc20: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
dc30: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
dc40: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
dc50: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
dc60: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
dc70: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
dc80: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
dc90: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
dca0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
dcb0: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
dcc0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
dcd0: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
dce0: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
dcf0: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
dd00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
dd10: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
dd20: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
dd30: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
dd40: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
dd50: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
dd60: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
dd70: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
dd80: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
dd90: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
dda0: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
ddb0: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
ddc0: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
ddd0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
dde0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ddf0: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
de00: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
de10: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
de20: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
de30: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
de40: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
de50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
de60: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
de70: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
de80: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
de90: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dea0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
deb0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dec0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ded0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dee0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
def0: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
df00: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
df10: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
df20: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
df30: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
df40: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
df50: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
df60: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
df70: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
df80: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
df90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
dfa0: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
dfb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
dfc0: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
dfd0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
dfe0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
dff0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
e000: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
e010: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
e020: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
e030: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
e040: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
e050: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
e060: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
e070: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
e080: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
e090: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
e0a0: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
e0b0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
e0c0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
e0d0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
e0e0: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
e0f0: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
e100: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
e110: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
e120: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
e130: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
e140: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
e150: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e160: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
e170: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e180: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
e190: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
e1a0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
e1b0: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
e1c0: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
e1d0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
e1e0: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
e1f0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
e200: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
e210: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
e220: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
e230: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
e240: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
e250: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
e260: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
e270: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
e280: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
e290: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
e2a0: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
e2b0: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
e2c0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
e2d0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
e2e0: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
e2f0: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
e300: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
e310: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
e320: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
e330: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
e340: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e350: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
e360: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
e370: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
e380: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
e390: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
e3a0: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
e3b0: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
e3c0: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
e3d0: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
e3e0: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
e3f0: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
e400: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
e410: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
e420: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
e430: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
e440: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
e450: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
e460: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
e470: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
e480: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
e490: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
e4a0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
e4b0: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
e4c0: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
e4d0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
e4e0: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
e4f0: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
e500: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
e510: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
e520: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
e530: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
e540: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
e550: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
e560: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
e570: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
e580: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
e590: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
e5a0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
e5b0: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
e5c0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
e5d0: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
e5e0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e5f0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
e600: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e610: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
e620: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
e630: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
e640: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
e650: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
e660: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
e670: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
e680: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
e690: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
e6a0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
e6b0: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
e6c0: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
e6d0: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
e6e0: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
e6f0: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
e700: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
e710: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
e720: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
e730: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
e740: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
e750: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
e760: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
e770: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
e780: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
e790: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
e7a0: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
e7b0: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
e7c0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
e7d0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
e7e0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
e7f0: 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
e800: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
e810: 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
e820: 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
e830: 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
e840: 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
e850: 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
e860: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
e870: 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
e880: 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
e890: 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
e8a0: 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
e8b0: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
e8c0: 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
e8d0: 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
e8e0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
e8f0: 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
e900: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
e910: 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
e920: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
e930: 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
e940: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
e950: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
e960: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
e970: 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
e980: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e990: 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
e9a0: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
e9b0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e9c0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e9d0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e9e0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
e9f0: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
ea00: 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
ea10: 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
ea20: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61   cache implemena
ea30: 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
ea40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
ea50: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
ea60: 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
ea70: 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
ea80: 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
ea90: 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
eaa0: 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
eab0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
eac0: 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
ead0: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
eae0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
eaf0: 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
eb00: 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
eb10: 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
eb20: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
eb30: 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
eb40: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
eb50: 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
eb60: 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
eb70: 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
eb80: 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
eb90: 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
eba0: 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
ebb0: 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
ebc0: 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
ebd0: 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
ebe0: 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
ebf0: 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
ec00: 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
ec10: 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
ec20: 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
ec30: 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
ec40: 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
ec50: 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
ec60: 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
ec70: 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
ec80: 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
ec90: 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
eca0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
ecb0: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
ecc0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
ecd0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
ece0: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
ecf0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
ed00: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
ed10: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
ed20: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ed30: 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
ed40: 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
ed50: 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
ed60: 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
ed70: 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
ed80: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
ed90: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
eda0: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
edb0: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
edc0: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
edd0: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
ede0: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
edf0: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
ee00: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
ee10: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
ee20: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
ee30: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ee40: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
ee50: 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
ee60: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
ee70: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
ee80: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
ee90: 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
eea0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
eeb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
eec0: 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
eed0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
eee0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
eef0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
ef00: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
ef10: 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
ef20: 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
ef30: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
ef40: 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
ef50: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
ef60: 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
ef70: 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
ef80: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ef90: 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
efa0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
efb0: 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
efc0: 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
efd0: 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
efe0: 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
eff0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
f000: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
f010: 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
f020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
f030: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
f040: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
f050: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
f060: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
f070: 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
f080: 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
f090: 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
f0a0: 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
f0b0: 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
f0c0: 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
f0d0: 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
f0e0: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
f0f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
f100: 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
f110: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
f120: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
f130: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
f140: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
f150: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
f160: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
f170: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
f180: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
f190: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f1a0: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
f1b0: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
f1c0: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
f1d0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
f1e0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
f1f0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
f200: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
f210: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
f220: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
f230: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
f240: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
f250: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
f260: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
f270: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
f280: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
f290: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
f2a0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f2b0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f2c0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f2d0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
f2e0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
f2f0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f300: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
f310: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
f320: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
f330: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
f340: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
f350: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
f360: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
f370: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
f380: 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
f390: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
f3a0: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
f3b0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
f3c0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
f3d0: 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
f3e0: 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
f3f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
f400: 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
f410: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
f420: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
f430: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
f440: 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
f450: 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
f460: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
f470: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
f480: 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
f490: 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
f4a0: 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
f4b0: 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
f4c0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f4d0: 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
f4e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f4f0: 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
f500: 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
f510: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
f520: 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
f530: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f540: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
f550: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f560: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f570: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f580: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f590: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
f5a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
f5b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
f5c0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
f5d0: 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
f5e0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f5f0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
f600: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
f610: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
f620: 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
f630: 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
f640: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
f650: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
f660: 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
f670: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
f680: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
f690: 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
f6a0: 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
f6b0: 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
f6c0: 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
f6d0: 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
f6e0: 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
f6f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
f700: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
f710: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
f720: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
f730: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
f740: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
f750: 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
f760: 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
f770: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
f780: 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
f790: 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
f7a0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f7b0: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
f7c0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
f7d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f7e0: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
f7f0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
f800: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
f810: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f820: 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
f830: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
f840: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
f850: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
f860: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
f870: 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
f880: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
f890: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
f8a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
f8b0: 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
f8c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
f8d0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f8e0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
f8f0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
f900: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
f910: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
f920: 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
f930: 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
f940: 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
f950: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
f960: 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
f970: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
f980: 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
f990: 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
f9a0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
f9b0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
f9c0: 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
f9d0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
f9e0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
f9f0: 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
fa00: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
fa10: 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
fa20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
fa30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
fa40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
fa50: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
fa60: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
fa70: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
fa80: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
fa90: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
faa0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
fab0: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
fac0: 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
fad0: 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
fae0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
faf0: 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
fb00: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
fb10: 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
fb20: 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
fb30: 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
fb40: 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
fb50: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
fb60: 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
fb70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
fb80: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
fb90: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
fba0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
fbb0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
fbc0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
fbd0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
fbe0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
fbf0: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
fc00: 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
fc10: 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
fc20: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
fc30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
fc40: 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
fc50: 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
fc60: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
fc70: 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
fc80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
fc90: 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
fca0: 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
fcb0: 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
fcc0: 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
fcd0: 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
fce0: 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
fcf0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
fd00: 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
fd10: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
fd20: 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
fd30: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
fd40: 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
fd50: 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
fd60: 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
fd70: 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
fd80: 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
fd90: 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
fda0: 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
fdb0: 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
fdc0: 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
fdd0: 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
fde0: 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
fdf0: 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
fe00: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
fe10: 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
fe20: 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
fe30: 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
fe40: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
fe50: 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
fe60: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
fe70: 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
fe80: 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
fe90: 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
fea0: 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
feb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
fec0: 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
fed0: 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
fee0: 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
fef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
ff00: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
ff10: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
ff20: 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
ff30: 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
ff40: 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
ff50: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
ff60: 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
ff70: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
ff80: 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
ff90: 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
ffa0: 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
ffb0: 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
ffc0: 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
ffd0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
ffe0: 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
fff0: 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
10000 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
10010 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
10020 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
10030 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
10040 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
10050 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
10060 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
10070 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
10080 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10090 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
100a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
100b0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
100c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
100d0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
100e0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
100f0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
10100 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
10110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
10120 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
10130 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
10140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
10150 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
10160 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10180 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
10190 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
101a0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
101b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
101c0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
101d0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
101e0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
101f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10200 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
10210 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
10220 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
10230 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10240 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
10250 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
10260 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
10270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10280 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
10290 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
102a0 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
102b0 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
102c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
102d0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
102e0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
102f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10300 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
10310 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
10320 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
10330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10340 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
10350 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
10360 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
10370 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
10380 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
10390 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
103a0 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
103b0 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
103c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
103d0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
103e0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
103f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10400 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
10410 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
10420 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
10430 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10440 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
10450 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
10460 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
10470 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10480 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
10490 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
104a0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
104b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
104c0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
104d0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
104e0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
104f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
10500 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
10510 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
10520 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10530 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
10540 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
10550 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10560 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
10570 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
10580 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
10590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
105a0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
105b0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
105c0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
105d0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
105e0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
105f0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
10600 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
10610 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
10620 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
10630 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
10640 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10650 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
10660 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
10670 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
10680 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10690 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
106a0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
106b0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
106c0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
106d0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
106e0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
106f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
10700 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
10710 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
10720 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10730 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
10740 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
10750 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
10760 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
10770 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
10780 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
10790 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
107a0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
107b0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
107c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
107d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
107e0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
107f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10800 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
10810 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
10820 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65  pointer to an me
10830 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
10840 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
10850 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
10860 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10870 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
10880 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10890 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
108a0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
108b0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
108c0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
108d0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
108e0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
108f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10900 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
10910 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
10920 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
10930 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
10940 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
10950 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
10960 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
10970 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
10980 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
10990 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
109a0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
109b0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
109c0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
109d0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
109e0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
109f0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
10a00 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
10a10 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
10a20 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
10a30 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
10a40 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
10a50 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10a60 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
10a70 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
10a80 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
10a90 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
10aa0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
10ab0 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20  ler.** multiple 
10ac0 6f 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f 3a  of 8.  See also:
10ad0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10ae0 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e 0a  LOOKASIDE]</dd>.
10af0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
10b00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
10b10 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10b20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
10b30 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a  d* int int */...
10b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10b50 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
10b60 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
10b70 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  t Codes.**.** ^T
10b80 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
10b90 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
10ba0 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
10bb0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
10bc0 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
10bd0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
10be0 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
10bf0 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
10c00 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
10c10 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
10c20 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
10c30 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
10c40 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ity..*/.int sqli
10c50 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
10c60 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
10c70 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
10c80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10c90 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
10ca0 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
10cb0 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
10cc0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
10cd0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
10ce0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
10cf0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
10d00 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
10d10 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
10d20 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
10d30 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
10d40 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
10d50 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
10d60 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
10d70 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
10d80 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
10d90 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
10da0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
10db0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
10dc0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
10dd0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
10de0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
10df0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
10e00 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
10e10 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
10e20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
10e30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
10e40 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
10e50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
10e60 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
10e70 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
10e80 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
10e90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10ea0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10eb0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
10ec0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
10ed0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
10ee0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
10ef0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
10f00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
10f10 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
10f20 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
10f30 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
10f40 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
10f50 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69  , then the [rowi
10f60 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
10f70 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74  ed.** row is ret
10f80 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
10f90 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73  utine as long as
10fa0 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20   the trigger is 
10fb0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
10fc0 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
10fd0 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65   terminates, the
10fe0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10ff0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  by this routine.
11000 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74 68  ** reverts to th
11010 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73  e last value ins
11020 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68 65  erted before the
11030 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e 29   trigger fired.)
11040 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
11050 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
11060 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
11070 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
11080 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
11090 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
110a0 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
110b0 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
110c0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
110d0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
110e0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
110f0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
11100 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
11110 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
11120 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
11130 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
11140 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
11150 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
11160 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
11170 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
11180 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
11190 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
111a0 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
111b0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
111c0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
111d0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
111e0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
111f0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
11200 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
11210 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
11220 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
11230 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
11240 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
11250 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
11260 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
11270 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
11280 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
11290 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
112a0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
112b0 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
112c0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
112d0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
112e0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
112f0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
11300 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
11310 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
11320 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
11330 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
11340 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
11350 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
11360 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
11370 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
11380 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
11390 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
113a0 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
113b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
113c0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
113d0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
113e0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
113f0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
11400 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
11410 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
11420 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
11430 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
11440 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
11450 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
11460 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
11470 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
11480 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
11490 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
114a0 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
114b0 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71  t [rowid]..*/.sq
114c0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
114d0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
114e0 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
114f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11500 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
11510 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
11520 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
11530 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
11540 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
11550 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
11560 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
11570 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
11580 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
11590 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
115a0 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
115b0 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
115c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
115d0 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
115e0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
115f0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c  ameter..** ^(Onl
11600 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
11610 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
11620 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e  ified by the [IN
11630 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c  SERT], [UPDATE],
11640 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  .** or [DELETE] 
11650 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f  statement are co
11660 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72  unted.  Auxiliar
11670 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  y changes caused
11680 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20   by.** triggers 
11690 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  or [foreign key 
116a0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74  actions] are not
116b0 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20   counted.)^ Use 
116c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
116d0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
116e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e   function to fin
116f0 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
11700 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a  er of changes.**
11710 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67   including chang
11720 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69  es caused by tri
11730 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67  ggers and foreig
11740 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a  n key actions..*
11750 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f  *.** ^Changes to
11760 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
11770 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e   simulated by an
11780 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
11790 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74  gger].** are not
117a0 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20   counted.  Only 
117b0 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67  real table chang
117c0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
117d0 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63  **.** ^(A "row c
117e0 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e  hange" is a chan
117f0 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72  ge to a single r
11800 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74  ow of a single t
11810 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62  able.** caused b
11820 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c  y an INSERT, DEL
11830 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73  ETE, or UPDATE s
11840 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20  tatement.  Rows 
11850 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e  that.** are chan
11860 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65  ged as side effe
11870 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d  cts of [REPLACE]
11880 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
11890 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
118a0 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
118b0 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42  ssing, [DROP TAB
118c0 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f  LE], or by any o
118d0 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73  ther.** mechanis
118e0 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  ms do not count 
118f0 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  as direct row ch
11900 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  anges.)^.**.** A
11910 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78   "trigger contex
11920 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66  t" is a scope of
11930 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20   execution that 
11940 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e  begins and.** en
11950 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69  ds with the scri
11960 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20  pt of a [CREATE 
11970 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
11980 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c  r]. .** Most SQL
11990 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
119a0 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74  ** evaluated out
119b0 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67  side of any trig
119c0 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68  ger.  This is th
119d0 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a  e "top level".**
119e0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
119f0 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20  .  If a trigger 
11a00 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74  fires from the t
11a10 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e  op level, a.** n
11a20 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
11a30 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f  xt is entered fo
11a40 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f  r the duration o
11a50 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72  f that one.** tr
11a60 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67  igger.  Subtrigg
11a70 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f  ers create subco
11a80 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72  ntexts for their
11a90 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   duration..**.**
11aa0 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74   ^Calling [sqlit
11ab0 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
11ac0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
11ad0 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
11ae0 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
11af0 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
11b00 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ext..**.** ^This
11b10 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11b20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
11b30 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
11b40 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73  es in the.** mos
11b50 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
11b60 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
11b70 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
11b80 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
11b90 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
11ba0 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68  .**.** ^Thus, wh
11bb0 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
11bc0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
11bd0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
11be0 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
11bf0 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
11c00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
11c10 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
11c20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
11c30 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
11c40 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
11c50 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20  .  ^(Within the 
11c60 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
11c70 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
11c80 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
11c90 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
11ca0 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
11cb0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
11cc0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
11cd0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
11ce0 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
11cf0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
11d00 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
11d10 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
11d20 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
11d30 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
11d40 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
11d50 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
11d60 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
11d70 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
11d80 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
11d90 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
11da0 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  text.)^.**.** Se
11db0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
11dc0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
11dd0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
11de0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
11df0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
11e00 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28  nd the [changes(
11e10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
11e20 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
11e30 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
11e40 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
11e50 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
11e60 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
11e70 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
11e80 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
11e90 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
11ea0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
11eb0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
11ec0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
11ed0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
11ee0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
11ef0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
11f00 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
11f10 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
11f20 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
11f30 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
11f40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
11f50 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
11f60 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
11f70 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
11f80 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
11f90 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
11fa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11fb0 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
11fc0 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
11fd0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
11fe0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
11ff0 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
12000 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
12010 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
12020 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
12030 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
12040 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
12050 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
12060 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
12070 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
12080 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
12090 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
120a0 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
120b0 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
120c0 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
120d0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
120e0 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
120f0 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
12100 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
12110 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
12120 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
12130 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
12140 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
12150 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
12160 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
12170 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
12180 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
12190 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
121a0 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
121b0 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
121c0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
121d0 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
121e0 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
121f0 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
12200 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
12210 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
12220 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
12230 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
12240 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
12250 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
12260 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
12270 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
12280 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
12290 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
122a0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
122b0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
122c0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
122d0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
122e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
122f0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
12300 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
12310 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
12320 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
12330 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
12340 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
12350 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
12360 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
12370 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
12380 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
12390 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
123a0 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
123b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
123c0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
123d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
123e0 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
123f0 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a  -Running Query.*
12400 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
12410 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70  ion causes any p
12420 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20  ending database 
12430 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f  operation to abo
12440 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e  rt and.** return
12450 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74   at its earliest
12460 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68   opportunity. Th
12470 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79  is routine is ty
12480 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  pically.** calle
12490 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  d in response to
124a0 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73   a user action s
124b0 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20  uch as pressing 
124c0 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43  "Cancel".** or C
124d0 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20  trl-C where the 
124e0 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e  user wants a lon
124f0 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f  g query operatio
12500 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d  n to halt.** imm
12510 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ediately..**.** 
12520 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63  ^It is safe to c
12530 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
12540 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
12550 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
12560 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
12570 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
12580 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
12590 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
125a0 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
125b0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
125c0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
125d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
125e0 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
125f0 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
12600 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
12610 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12620 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
12630 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65  * ^If an SQL ope
12640 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e  ration is very n
12650 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61  early finished a
12660 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a  t the time when.
12670 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  ** sqlite3_inter
12680 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64  rupt() is called
12690 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20  , then it might 
126a0 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f  not have an oppo
126b0 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65  rtunity.** to be
126c0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64   interrupted and
126d0 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20   might continue 
126e0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a  to completion..*
126f0 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65  *.** ^An SQL ope
12700 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
12710 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
12720 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
12730 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49  NTERRUPT]..** ^I
12740 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
12750 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
12760 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
12770 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
12780 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
12790 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
127a0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
127b0 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
127c0 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
127d0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
127e0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
127f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
12800 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c  interrupt(D) cal
12810 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75  l is in effect u
12820 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74  ntil all current
12830 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  ly running.** SQ
12840 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20  L statements on 
12850 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12860 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65  tion] D complete
12870 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20  .  ^Any new SQL 
12880 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
12890 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
128a0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
128b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
128c0 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65  l and before the
128d0 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61   .** running sta
128e0 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20  tements reaches 
128f0 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75  zero are interru
12900 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20  pted as if they 
12910 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e  had been.** runn
12920 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65  ing prior to the
12930 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
12940 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77  pt() call.  ^New
12950 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
12960 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
12970 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75  ted after the ru
12980 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  nning statement 
12990 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65  count reaches ze
129a0 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66  ro are.** not ef
129b0 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71  fected by the sq
129c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
129d0 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  )..** ^A call to
129e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
129f0 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72  pt(D) that occur
12a00 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65  s when there are
12a10 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53   no running.** S
12a20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73  QL statements is
12a30 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73   a no-op and has
12a40 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51   no effect on SQ
12a50 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
12a60 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
12a70 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
12a80 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
12a90 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  all returns..**.
12aa0 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61  ** If the databa
12ab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
12ac0 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69  oses while [sqli
12ad0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d  te3_interrupt()]
12ae0 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  .** is running t
12af0 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
12b00 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
12b10 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
12b20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
12b30 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
12b40 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
12b50 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
12b60 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
12b70 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
12b80 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
12b90 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
12ba0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
12bb0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
12bc0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
12bd0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
12be0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
12bf0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
12c00 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
12c10 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
12c20 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
12c30 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
12c40 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
12c50 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
12c60 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12c70 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
12c80 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
12c90 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
12ca0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
12cb0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
12cc0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
12cd0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
12ce0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
12cf0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
12d00 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
12d10 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
12d20 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
12d30 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
12d40 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
12d50 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
12d60 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
12d70 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
12d80 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
12d90 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
12da0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
12db0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
12dc0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
12dd0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
12de0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
12df0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
12e00 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
12e10 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
12e20 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
12e30 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
12e40 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
12e50 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
12e60 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
12e70 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
12e80 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
12e90 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
12ea0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
12eb0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
12ec0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12ed0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
12ee0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
12ef0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
12f00 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
12f10 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
12f20 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
12f30 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
12f40 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
12f50 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
12f60 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
12f70 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
12f80 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
12f90 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
12fa0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
12fb0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
12fc0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
12fd0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
12fe0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
12ff0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
13000 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
13010 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
13020 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
13030 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
13040 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
13050 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
13060 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13070 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
13080 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
13090 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
130a0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
130b0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
130c0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
130d0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
130e0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
130f0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
13100 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
13110 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
13120 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
13130 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
13140 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
13150 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
13160 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
13170 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
13180 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
13190 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
131a0 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
131b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
131c0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
131d0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
131e0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
131f0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
13200 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
13210 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
13220 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
13230 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
13240 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
13250 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
13260 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
13270 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
13280 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
13290 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
132a0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
132b0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
132c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
132d0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
132e0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
132f0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
13300 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13310 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
13320 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
13330 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
13340 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
13350 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
13360 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
13370 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
13380 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
13390 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
133a0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
133b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
133c0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
133d0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
133e0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
133f0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
13400 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
13410 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
13420 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
13430 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13440 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
13450 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
13460 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
13470 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
13480 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13490 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
134a0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
134b0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
134c0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
134d0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
134e0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
134f0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
13500 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
13510 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
13520 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
13530 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
13540 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
13550 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
13560 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
13570 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
13580 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
13590 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
135a0 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
135b0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
135c0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
135d0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
135e0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
135f0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
13600 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
13610 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
13620 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
13630 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
13640 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
13650 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
13660 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
13670 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
13680 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
13690 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
136a0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
136b0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
136c0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
136d0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
136e0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
136f0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
13700 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
13710 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
13720 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
13730 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
13740 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
13750 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
13760 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
13770 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
13780 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
13790 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
137a0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
137b0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
137c0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
137d0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
137e0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
137f0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
13800 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
13810 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
13820 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
13830 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
13840 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
13850 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
13860 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
13870 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
13880 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
13890 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
138a0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
138b0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
138c0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
138d0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
138e0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
138f0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
13900 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
13910 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
13920 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
13930 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
13940 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
13950 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
13960 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
13970 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
13980 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
13990 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
139a0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
139b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
139c0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
139d0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
139e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
139f0 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
13a00 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
13a10 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
13a20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
13a30 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
13a40 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
13a50 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
13a60 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
13a70 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
13a80 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
13a90 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
13aa0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
13ab0 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
13ac0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
13ad0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
13ae0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
13af0 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
13b00 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
13b10 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
13b20 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
13b30 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
13b40 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
13b50 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
13b60 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
13b70 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
13b80 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
13b90 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
13ba0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
13bb0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
13bc0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
13bd0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
13be0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
13bf0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
13c00 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
13c10 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
13c20 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
13c30 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
13c40 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
13c50 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
13c60 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
13c70 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
13c80 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
13c90 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
13ca0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
13cb0 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
13cc0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
13cd0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
13ce0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
13cf0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
13d00 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
13d10 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
13d20 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
13d30 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
13d40 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
13d50 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
13d60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
13d70 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
13d80 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
13d90 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
13da0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
13db0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
13dc0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
13dd0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
13de0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
13df0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
13e00 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
13e10 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
13e20 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
13e30 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
13e40 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
13e50 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
13e60 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
13e70 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
13e80 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
13e90 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
13ea0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
13eb0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
13ec0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
13ed0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
13ee0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
13ef0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
13f00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13f10 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
13f20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
13f30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
13f40 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
13f50 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
13f60 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
13f70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13f80 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
13f90 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
13fa0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
13fb0 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
13fc0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
13fd0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
13fe0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
13ff0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
14000 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
14010 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
14020 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
14030 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
14040 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
14050 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
14060 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
14070 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
14080 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
14090 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
140a0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
140b0 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
140c0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
140d0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
140e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
140f0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
14100 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
14110 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
14120 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
14130 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
14140 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
14150 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
14160 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
14170 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
14180 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
14190 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
141a0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
141b0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
141c0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
141d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
141e0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
141f0 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
14200 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
14210 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
14220 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
14230 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
14240 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
14250 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
14260 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
14270 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
14280 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
14290 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
142a0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
142b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
142c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
142d0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
142e0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
142f0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
14300 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
14310 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
14320 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
14330 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
14340 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
14350 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14360 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
14370 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
14380 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
14390 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
143a0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
143b0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
143c0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
143d0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
143e0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
143f0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
14400 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
14410 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
14420 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
14430 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
14440 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
14450 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
14460 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
14470 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
14480 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
14490 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
144a0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
144b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
144c0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
144d0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
144e0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
144f0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
14500 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
14510 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
14520 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
14530 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
14540 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
14550 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
14560 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
14570 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
14580 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
14590 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
145a0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
145b0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
145c0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
145d0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
145e0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
145f0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
14600 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
14610 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
14620 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
14630 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
14640 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
14650 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
14660 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
14670 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
14680 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
14690 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
146a0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
146b0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
146c0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
146d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
146e0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
146f0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
14700 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
14710 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
14720 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
14730 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  * As an example 
14740 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14750 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
14760 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
14770 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
14780 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14790 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
147a0 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
147b0 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
147c0 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
147d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
147e0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
147f0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
14800 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
14810 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
14820 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
14830 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14840 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
14850 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
14860 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
14870 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
14880 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
14890 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
148a0 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
148b0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
148c0 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
148d0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
148e0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
148f0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
14900 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
14910 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14920 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
14930 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
14940 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
14950 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
14960 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
14970 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14980 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
14990 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
149a0 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
149b0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
149c0 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
149d0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
149e0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
149f0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
14a00 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
14a10 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
14a20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14a30 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
14a40 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14a50 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te>.**.** ^The s
14a60 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14a70 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
14a80 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
14a90 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
14aa0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
14ab0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
14ac0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
14ad0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
14ae0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
14af0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
14b00 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
14b10 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
14b20 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
14b30 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
14b40 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
14b50 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
14b60 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
14b70 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
14b80 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
14b90 2a 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61 73  ** it should pas
14ba0 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
14bb0 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
14bc0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14bd0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14be0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14bf0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14c00 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14c10 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14c20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14c30 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14c40 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14c50 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14c60 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14c70 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14c80 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14c90 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14ca0 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14cb0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14cc0 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14cd0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14ce0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14cf0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
14d00 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
14d10 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
14d20 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
14d30 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
14d40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
14d50 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
14d60 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14d70 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
14d80 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
14d90 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
14da0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
14db0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
14dc0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
14dd0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
14de0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
14df0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
14e00 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
14e10 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
14e20 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
14e30 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
14e40 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
14e50 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
14e60 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
14e70 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
14e80 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
14e90 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
14ea0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
14eb0 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  )].)^.*/.int sql
14ec0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
14ed0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
14ee0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
14ef0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
14f00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
14f10 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
14f20 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
14f30 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
14f40 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
14f50 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
14f60 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
14f70 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
14f80 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
14f90 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
14fa0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
14fb0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
14fc0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
14fd0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
14fe0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
14ff0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
15000 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
15010 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
15020 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
15030 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
15040 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
15050 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
15060 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
15070 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
15080 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
15090 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
150a0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
150b0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
150c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
150d0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
150e0 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  library..**.** ^
150f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  The sqlite3_mpri
15100 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ntf() and sqlite
15110 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75  3_vmprintf() rou
15120 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69  tines write thei
15130 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  r.** results int
15140 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
15150 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
15160 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68  malloc()]..** Th
15170 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
15180 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20  ed by these two 
15190 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
151a0 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62  be.** released b
151b0 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  y [sqlite3_free(
151c0 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69  )].  ^Both routi
151d0 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
151e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
151f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15200 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
15210 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
15220 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
15230 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
15240 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28  string..**.** ^(
15250 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
15260 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
15270 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
15280 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
15290 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
152a0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
152b0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
152c0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
152d0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
152e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
152f0 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
15300 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
15310 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15320 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
15330 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
15340 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
15350 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
15360 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
15370 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
15380 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
15390 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
153a0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
153b0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
153c0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
153d0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
153e0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
153f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
15400 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
15410 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
15420 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
15430 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
15440 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
15450 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
15460 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
15470 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
15480 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
15490 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
154a0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
154b0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
154c0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
154d0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
154e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
154f0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
15500 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
15510 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
15520 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
15530 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
15540 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
15550 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
15560 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
15570 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
15580 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
15590 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
155a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
155b0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
155c0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
155d0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
155e0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
155f0 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
15600 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
15610 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
15620 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
15630 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
15640 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
15650 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
15660 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
15670 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
15680 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
15690 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
156a0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
156b0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
156c0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
156d0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
156e0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
156f0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
15700 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
15710 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
15720 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
15730 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
15740 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
15750 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
15760 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
15770 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
15780 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
15790 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e  es a null-termin
157a0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
157b0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
157c0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
157d0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
157e0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
157f0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
15800 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
15810 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
15820 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
15830 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
15840 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
15850 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
15860 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
15870 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
15880 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
15890 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
158a0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
158b0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
158c0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
158d0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
158e0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
158f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15900 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
15910 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
15920 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
15930 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15940 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
15950 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
15960 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
15970 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
15980 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
15990 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
159a0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
159b0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
159c0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
159d0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
159e0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
159f0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
15a00 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
15a10 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
15a20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
15a30 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
15a40 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
15a50 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
15a60 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
15a70 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
15a80 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
15a90 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
15aa0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
15ab0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
15ac0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
15ad0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
15ae0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
15af0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
15b00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15b10 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
15b20 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
15b30 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
15b40 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
15b50 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
15b60 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
15b70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15b80 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
15b90 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15ba0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
15bb0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
15bc0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15bd0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
15be0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
15bf0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
15c00 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
15c10 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
15c20 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
15c30 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
15c40 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
15c50 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
15c60 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
15c70 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
15c80 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
15c90 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
15ca0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
15cb0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
15cc0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
15cd0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
15ce0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
15cf0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
15d00 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
15d10 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
15d20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
15d30 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
15d40 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
15d50 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
15d60 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
15d70 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
15d80 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
15d90 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
15da0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
15db0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
15dc0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
15dd0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
15de0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
15df0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
15e00 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
15e10 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
15e20 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
15e30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
15e40 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
15e50 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
15e60 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
15e70 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
15e80 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
15e90 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
15ea0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
15eb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
15ec0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
15ed0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
15ee0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
15ef0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
15f00 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
15f10 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
15f20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
15f30 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
15f40 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
15f50 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
15f60 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
15f70 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
15f80 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
15f90 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
15fa0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
15fb0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
15fc0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
15fd0 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
15fe0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
15ff0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
16000 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  har*, ...);../*.
16010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
16020 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
16030 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
16040 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
16050 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
16060 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
16070 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
16080 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
16090 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
160a0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
160b0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
160c0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
160d0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
160e0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
160f0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
16100 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
16110 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
16120 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
16130 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
16140 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
16150 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
16160 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
16170 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16180 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
16190 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
161a0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
161b0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
161c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
161d0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
161e0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
161f0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
16200 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
16210 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
16220 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16230 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
16240 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
16250 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
16260 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
16270 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
16280 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
16290 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
162a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
162b0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
162c0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
162d0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
162e0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
162f0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
16300 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16310 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
16320 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
16330 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
16340 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
16350 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
16360 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
16370 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
16380 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16390 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
163a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
163b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
163c0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
163d0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
163e0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
163f0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
16400 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
16410 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
16420 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
16430 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
16440 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
16450 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
16460 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
16470 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
16480 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
16490 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
164a0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
164b0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
164c0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
164d0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
164e0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
164f0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
16500 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
16510 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
16520 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
16530 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
16540 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
16550 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
16560 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
16570 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
16580 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
16590 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
165a0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
165b0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
165c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
165d0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
165e0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
165f0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
16600 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
16610 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
16620 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
16630 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16640 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
16650 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
16660 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
16670 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
16680 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
16690 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
166a0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
166b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
166c0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
166d0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
166e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
166f0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
16700 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
16710 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
16720 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
16730 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
16740 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
16750 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
16760 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
16770 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16780 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
16790 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
167a0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
167b0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
167c0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
167d0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
167e0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
167f0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
16800 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
16810 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
16820 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
16830 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16840 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
16850 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
16860 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
16870 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
16880 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
16890 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
168a0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
168b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
168c0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
168d0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
168e0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
168f0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
16900 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
16910 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
16920 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
16930 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
16940 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
16950 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16960 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
16970 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
16980 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
16990 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
169a0 65 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a  e boundary..**.*
169b0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
169c0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
169d0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
169e0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
169f0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
16a00 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
16a10 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
16a20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
16a30 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
16a40 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
16a50 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
16a60 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
16a70 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
16a80 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
16a90 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
16aa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
16ab0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
16ac0 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
16ad0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
16ae0 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
16af0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
16b00 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
16b10 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
16b20 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
16b30 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
16b40 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
16b50 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
16b60 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
16b70 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
16b80 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
16b90 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
16ba0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
16bb0 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
16bc0 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
16bd0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
16be0 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
16bf0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
16c00 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
16c10 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
16c20 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
16c30 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
16c40 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
16c50 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
16c60 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
16c70 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
16c80 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
16c90 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
16ca0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
16cb0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
16cc0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
16cd0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
16ce0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
16cf0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
16d00 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
16d10 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
16d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
16d30 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
16d40 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
16d50 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
16d60 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
16d70 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
16d80 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
16d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
16da0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
16db0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
16dc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
16dd0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
16de0 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
16df0 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
16e00 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
16e10 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
16e20 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
16e30 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
16e40 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
16e50 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
16e60 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
16e70 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
16e80 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
16e90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
16ea0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
16eb0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
16ec0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
16ed0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
16ee0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
16ef0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
16f00 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
16f10 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
16f20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16f30 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
16f40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
16f50 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
16f60 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
16f70 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
16f80 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
16f90 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
16fa0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
16fb0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
16fc0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
16fd0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
16fe0 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
16ff0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
17000 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
17010 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
17020 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
17030 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
17040 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
17050 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
17060 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
17070 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
17080 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
17090 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
170a0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
170b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
170c0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
170d0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
170e0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
170f0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
17100 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
17110 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
17120 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
17130 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
17140 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
17150 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
17160 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
17170 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
17180 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
17190 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
171a0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
171b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
171c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
171d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
171e0 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
171f0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
17200 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
17210 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
17220 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
17230 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
17240 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
17250 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
17260 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
17270 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
17280 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
17290 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
172a0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
172b0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
172c0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
172d0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
172e0 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
172f0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
17300 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
17310 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
17320 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
17330 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
17340 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
17350 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
17360 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
17370 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
17380 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
17390 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
173a0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
173b0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
173c0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
173d0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
173e0 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
173f0 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
17400 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
17410 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
17420 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
17430 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
17440 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
17450 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
17460 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
17470 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
17480 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
17490 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
174a0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
174b0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
174c0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
174d0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
174e0 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
174f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
17500 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
17510 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
17520 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
17530 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
17540 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
17550 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
17560 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
17570 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
17580 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
17590 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
175a0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
175b0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
175c0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
175d0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
175e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
175f0 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
17600 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  thod..*/.void sq
17610 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
17620 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
17630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17640 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
17650 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
17660 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
17670 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
17680 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
17690 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
176a0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
176b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
176c0 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
176d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
176e0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
176f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17700 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
17710 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
17720 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
17730 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
17740 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
17750 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
17760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17770 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
17780 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
17790 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
177a0 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
177b0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
177c0 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
177d0 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
177e0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
177f0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
17800 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
17810 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
17820 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17830 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
17840 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
17850 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
17860 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
17870 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17880 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
17890 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
178a0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
178b0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
178c0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
178d0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
178e0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
178f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
17900 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
17910 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
17920 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
17930 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
17940 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
17950 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
17960 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
17970 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
17980 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17990 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
179a0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
179b0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
179c0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
179d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
179e0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
179f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17a00 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
17a10 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
17a20 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
17a30 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
17a40 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
17a50 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
17a60 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
17a70 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
17a80 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
17a90 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
17aa0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
17ab0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
17ac0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
17ad0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
17ae0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
17af0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
17b00 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
17b10 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
17b20 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
17b30 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
17b40 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
17b50 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
17b60 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
17b70 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
17b80 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17b90 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
17ba0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
17bb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
17bc0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
17bd0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
17be0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17bf0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
17c00 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17c10 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
17c20 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
17c30 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
17c40 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
17c50 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
17c60 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
17c70 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
17c80 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
17c90 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
17ca0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
17cb0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
17cc0 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
17cd0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
17ce0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
17cf0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
17d00 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
17d10 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
17d20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
17d30 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
17d40 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
17d50 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
17d60 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17d70 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
17d80 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
17d90 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
17da0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
17db0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
17dc0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
17dd0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
17de0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
17df0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
17e00 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
17e10 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
17e20 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
17e30 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
17e40 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
17e50 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
17e60 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
17e70 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
17e80 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
17e90 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
17ea0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
17eb0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
17ec0 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
17ed0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
17ee0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
17ef0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
17f00 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
17f10 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
17f20 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
17f30 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
17f40 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
17f50 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
17f60 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
17f70 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
17f80 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
17f90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17fa0 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
17fb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17fc0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
17fd0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
17fe0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
17ff0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
18000 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
18010 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
18020 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
18030 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
18040 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
18050 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
18060 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
18070 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
18080 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
18090 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
180a0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
180b0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
180c0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
180d0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
180e0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
180f0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
18100 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
18110 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
18120 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
18130 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
18140 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
18150 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
18160 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
18170 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
18180 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
18190 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
181a0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
181b0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
181c0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
181d0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
181e0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
181f0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
18200 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
18210 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
18220 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
18230 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
18240 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
18250 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
18260 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
18270 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
18280 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
18290 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
182a0 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
182b0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
182c0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
182d0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
182e0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
182f0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
18300 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
18310 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
18320 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
18330 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
18340 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
18350 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
18360 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
18370 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
18380 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
18390 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
183a0 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
183b0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
183c0 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
183d0 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
183e0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
183f0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
18400 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
18410 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
18420 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
18430 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
18440 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
18450 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
18460 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
18470 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18480 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
18490 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
184a0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
184b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
184c0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
184d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
184e0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
184f0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
18500 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
18510 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
18520 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
18530 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
18540 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
18550 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
18560 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
18570 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
18580 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
18590 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
185a0 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
185b0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
185c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
185d0 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
185e0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
185f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18600 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
18610 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
18620 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
18630 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
18640 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18650 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18660 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
18670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
18680 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
18690 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
186a0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
186b0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
186c0 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
186d0 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
186e0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
186f0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
18700 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
18710 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
18720 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
18730 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
18740 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
18750 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
18760 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
18770 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
18780 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
18790 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
187a0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
187b0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
187c0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
187d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
187e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
187f0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
18800 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
18810 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
18820 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
18830 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
18840 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18850 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
18860 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
18870 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
18880 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
18890 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
188a0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
188b0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
188c0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
188d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
188e0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
188f0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
18900 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
18910 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
18920 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
18930 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
18940 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
18950 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  on..*/.#define S
18960 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
18970 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
18980 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
18990 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
189a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
189b0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
189c0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
189d0 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
189e0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
189f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
18a00 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
18a10 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
18a20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
18a30 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
18a40 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
18a50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18a60 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
18a70 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
18a80 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
18a90 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
18aa0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
18ab0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18ac0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
18ad0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
18ae0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
18af0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
18b00 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
18b10 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
18b20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
18b30 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
18b40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b50 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
18b60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
18b70 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
18b80 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
18b90 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
18ba0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
18bb0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
18bc0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
18bd0 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
18be0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
18bf0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18c00 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
18c10 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
18c20 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
18c30 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
18c40 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
18c50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
18c60 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
18c70 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
18c80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18c90 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
18ca0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
18cb0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
18cc0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
18cd0 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
18ce0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
18cf0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
18d00 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
18d10 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18d20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
18d30 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
18d40 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
18d50 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
18d60 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
18d70 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
18d80 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
18d90 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
18da0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
18db0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
18dc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18dd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
18de0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
18df0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
18e00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e10 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
18e20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
18e30 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18e40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e60 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
18e70 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
18e80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
18e90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18eb0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
18ec0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
18ed0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
18ee0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18f00 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
18f10 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
18f20 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
18f30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18f50 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
18f60 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
18f70 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
18f80 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18fa0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
18fb0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
18fc0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18fd0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18fe0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18ff0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
19000 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
19010 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19020 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19030 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19040 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
19050 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
19060 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19070 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19080 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
19090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
190a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
190b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
190c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
190d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
190e0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
190f0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
19100 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
19110 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19120 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
19130 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
19140 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19150 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19160 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19170 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
19180 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
19190 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
191a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
191b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
191c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
191d0 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
191e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
191f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19200 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19210 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
19220 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
19230 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
19240 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19260 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
19270 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
19280 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
19290 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
192a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
192b0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
192c0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
192d0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
192e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
192f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19300 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
19310 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
19320 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
19330 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19350 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
19360 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
19370 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19380 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
193a0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
193b0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
193c0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
193d0 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
193e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
193f0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
19400 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
19410 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
19420 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
19430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
19440 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
19450 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
19460 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
19470 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
19480 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
19490 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
194a0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
194b0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
194c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
194d0 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
194e0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
194f0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
19500 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
19510 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19520 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
19530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
19540 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
19550 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19560 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19570 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
19580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
19590 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
195a0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
195b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
195c0 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
195d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
195e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
195f0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
19600 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19610 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
19620 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
19630 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
19640 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19650 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19660 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
19670 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
19680 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19690 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
196a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
196b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
196c0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
196d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
196e0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
196f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19700 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
19710 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
19720 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19730 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
19740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19750 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
19760 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
19770 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19780 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
19790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
197a0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
197b0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
197c0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
197d0 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
197e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
197f0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
19800 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
19810 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
19820 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19830 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
19840 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
19850 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19860 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
19870 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19880 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
19890 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
198a0 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
198b0 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
198c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
198d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
198e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
198f0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
19900 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
19910 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
19920 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
19930 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19940 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
19950 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19960 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
19970 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
19980 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
19990 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
199a0 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
199b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
199c0 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
199d0 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
199e0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
199f0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
19a00 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
19a10 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
19a20 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
19a30 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
19a40 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
19a50 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
19a60 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
19a70 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
19a80 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
19a90 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
19aa0 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  gger.)^.**.** ^T
19ab0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
19ac0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
19ad0 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
19ae0 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
19af0 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
19b00 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
19b10 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
19b20 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
19b30 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
19b40 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
19b50 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
19b60 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
19b70 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
19b80 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
19b90 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
19ba0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
19bb0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
19bc0 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
19bd0 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
19be0 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
19bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
19c00 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
19c10 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
19c20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
19c30 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
19c40 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
19c50 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
19c60 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
19c70 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
19c80 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
19c90 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
19ca0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
19cb0 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
19cc0 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
19cd0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19ce0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
19cf0 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
19d00 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
19d10 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
19d20 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
19d30 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
19d40 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
19d50 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
19d60 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
19d70 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
19d80 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
19d90 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
19da0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
19db0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
19dc0 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
19dd0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
19de0 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
19df0 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
19e00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
19e10 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
19e20 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
19e30 69 73 20 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69  is routine confi
19e40 67 75 72 65 73 20 61 20 63 61 6c 6c 62 61 63 6b  gures a callback
19e50 20 66 75 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a   function - the.
19e60 2a 2a 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  ** progress call
19e70 62 61 63 6b 20 2d 20 74 68 61 74 20 69 73 20 69  back - that is i
19e80 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
19e90 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a  lly during long.
19ea0 2a 2a 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ** running calls
19eb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
19ec0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
19ed0 74 65 70 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  tep()] and.** [s
19ee0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19ef0 28 29 5d 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ()].  An example
19f00 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
19f10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
19f20 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
19f30 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
19f40 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
19f50 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
19f60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
19f70 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
19f80 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
19f90 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
19fa0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
19fb0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
19fc0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
19fd0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
19fe0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
19ff0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1a000 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1a010 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  r must not do an
1a020 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1a030 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1a040 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a050 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1a060 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1a070 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1a080 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1a090 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1a0a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1a0b0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1a0c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1a0d0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1a0e0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1a0f0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1a100 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
1a110 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1a120 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1a130 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1a140 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1a150 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a160 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1a170 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1a180 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1a190 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1a1a0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1a1b0 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61  se file whose na
1a1c0 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  me is given by t
1a1d0 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  he.** filename a
1a1e0 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
1a1f0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1a200 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1a210 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
1a220 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1a230 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1a240 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
1a250 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1a260 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
1a270 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
1a280 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
1a290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1a2a0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
1a2b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
1a2c0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
1a2d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
1a2e0 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
1a2f0 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
1a300 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
1a310 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
1a320 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1a330 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
1a340 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
1a350 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
1a360 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
1a370 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
1a380 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
1a390 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
1a3a0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1a3b0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
1a3c0 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
1a3d0 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
1a3e0 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
1a3f0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
1a400 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
1a410 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
1a420 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
1a430 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
1a440 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1a450 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
1a460 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
1a470 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
1a480 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
1a490 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
1a4a0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
1a4b0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
1a4c0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1a4d0 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
1a4e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1a4f0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
1a500 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69   the database wi
1a510 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a  ll be UTF-8 if.*
1a520 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1a530 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1a540 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
1a550 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e  and.** UTF-16 in
1a560 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1a570 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65   order if sqlite
1a580 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73  3_open16() is us
1a590 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65  ed..**.** Whethe
1a5a0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f  r or not an erro
1a5b0 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74  r occurs when it
1a5c0 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f   is opened, reso
1a5d0 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61  urces.** associa
1a5e0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1a5f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a600 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64  n] handle should
1a610 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a   be released by.
1a620 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  ** passing it to
1a630 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
1a640 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f  )] when it is no
1a650 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64   longer required
1a660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1a670 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e  te3_open_v2() in
1a680 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69  terface works li
1a690 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ke sqlite3_open(
1a6a0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ).** except that
1a6b0 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20   it accepts two 
1a6c0 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d  additional param
1a6d0 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69  eters for additi
1a6e0 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  onal control.** 
1a6f0 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74  over the new dat
1a700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a710 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70  .  ^(The flags p
1a720 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73  arameter to.** s
1a730 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a740 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66   can take one of
1a750 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
1a760 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20  g three values, 
1a770 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
1a780 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  ned with the .**
1a790 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1a7a0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
1a7b0 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c  OPEN_FULLMUTEX],
1a7c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1a7d0 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61  AREDCACHE],.** a
1a7e0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
1a7f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1a800 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
1a810 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
1a820 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1a830 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1a840 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1a850 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1a860 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1a870 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1a880 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1a890 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1a8a0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1a8b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1a8c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1a8d0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1a8e0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1a8f0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1a900 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1a910 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1a920 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1a930 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1a940 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1a950 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1a960 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1a970 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1a980 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1a990 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1a9a0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1a9b0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1a9c0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1a9d0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1a9e0 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1a9f0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1aa00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1aa10 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1aa20 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1aa30 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1aa40 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
1aa50 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1aa60 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1aa70 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1aa80 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1aa90 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1aaa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1aab0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1aac0 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  6().</dd>)^.** <
1aad0 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  /dl>.**.** If th
1aae0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
1aaf0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1ab00 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  v2() is not one 
1ab10 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e  of the.** combin
1ab20 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1ab30 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  ve or one of the
1ab40 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
1ab50 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e  own above combin
1ab60 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
1ab70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1ab80 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1ab90 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a  EN_FULLMUTEX],.*
1aba0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  * [SQLITE_OPEN_S
1abb0 48 41 52 45 44 43 41 43 48 45 5d 20 61 6e 64 2f  HAREDCACHE] and/
1abc0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
1abd0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1abe0 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
1abf0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1ac00 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
1ac10 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1ac20 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1ac30 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
1ac40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ac50 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
1ac60 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
1ac70 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
1ac80 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
1ac90 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
1aca0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
1acb0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
1acc0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1acd0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
1ace0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1acf0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1ad00 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
1ad10 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1ad20 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
1ad30 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1ad40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1ad50 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
1ad60 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
1ad70 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
1ad80 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
1ad90 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1ada0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
1adb0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1adc0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1add0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ade0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
1adf0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
1ae00 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1ae10 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
1ae20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1ae30 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
1ae40 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
1ae50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
1ae60 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
1ae70 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
1ae80 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
1ae90 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
1aea0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1aeb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
1aec0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
1aed0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
1aee0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
1aef0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
1af00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1af10 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
1af20 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
1af30 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
1af40 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1af50 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
1af60 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1af70 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
1af80 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1af90 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1afa0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1afb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1afc0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1afd0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1afe0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1aff0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1b000 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1b010 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1b020 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1b030 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1b040 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1b050 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1b060 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1b070 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1b080 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1b090 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1b0a0 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1b0b0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1b0c0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1b0d0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1b0e0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
1b0f0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1b100 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
1b110 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
1b120 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
1b130 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
1b140 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
1b150 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
1b160 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1b170 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1b180 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1b190 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1b1a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1b1b0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   closed..**.** ^
1b1c0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1b1d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1b1e0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1b1f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1b200 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1b210 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1b220 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1b230 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1b240 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1b250 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b260 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1b270 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1b280 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1b290 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1b2a0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1b2b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1b2c0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1b2d0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
1b2e0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
1b2f0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
1b300 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
1b310 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
1b320 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
1b330 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1b340 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
1b350 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
1b360 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
1b370 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
1b380 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
1b390 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
1b3a0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
1b3b0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
1b3c0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
1b3d0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
1b3e0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
1b3f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1b400 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1b410 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 69 6e 74 20  en_v2()..*/.int 
1b420 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
1b430 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1b440 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1b450 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1b460 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1b470 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1b480 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1b490 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1b4a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1b4b0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
1b4c0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
1b4d0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1b4e0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
1b4f0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1b500 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1b510 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1b520 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1b530 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
1b540 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1b550 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1b560 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1b570 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1b580 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
1b590 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1b5a0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
1b5b0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
1b5c0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
1b5d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1b5e0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
1b5f0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
1b600 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
1b610 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b620 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
1b630 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
1b640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1b650 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
1b660 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1b670 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
1b680 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
1b690 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1b6a0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1b6b0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
1b6c0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
1b6d0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1b6e0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
1b6f0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
1b700 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
1b710 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
1b720 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
1b730 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
1b740 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1b750 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
1b760 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
1b770 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
1b780 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
1b790 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
1b7a0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
1b7b0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
1b7c0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
1b7d0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
1b7e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1b7f0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
1b800 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1b810 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
1b820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b830 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
1b840 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
1b850 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
1b860 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
1b870 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
1b880 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
1b890 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1b8a0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
1b8b0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
1b8c0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1b8d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1b8e0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1b8f0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1b900 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1b910 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1b920 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1b930 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1b940 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1b950 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1b960 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1b970 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1b980 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1b990 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1b9a0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1b9b0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
1b9c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
1b9d0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1b9e0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
1b9f0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
1ba00 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
1ba10 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
1ba20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
1ba30 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
1ba40 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
1ba50 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
1ba60 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
1ba70 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
1ba80 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
1ba90 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
1baa0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
1bab0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
1bac0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
1bad0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
1bae0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
1baf0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
1bb00 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
1bb10 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
1bb20 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
1bb30 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
1bb40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bb50 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
1bb60 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1bb70 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
1bb80 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1bb90 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
1bba0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
1bbb0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
1bbc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
1bbd0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
1bbe0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
1bbf0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
1bc00 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
1bc10 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
1bc20 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
1bc30 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
1bc40 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
1bc50 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
1bc60 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
1bc70 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
1bc80 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
1bc90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1bca0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
1bcb0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
1bcc0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
1bcd0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
1bce0 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
1bcf0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
1bd00 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
1bd10 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1bd20 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1bd30 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1bd40 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1bd50 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1bd60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1bd70 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1bd80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1bd90 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1bda0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  nt Object.** KEY
1bdb0 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1bdc0 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1bdd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1bde0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1bdf0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1be00 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1be10 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1be20 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1be30 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1be40 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1be50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1be60 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1be70 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1be80 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1be90 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1bea0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1beb0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1bec0 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1bed0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1bee0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1bef0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1bf00 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1bf10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1bf20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1bf30 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1bf40 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1bf50 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1bf60 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1bf70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1bf80 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1bf90 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1bfa0 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1bfb0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1bfc0 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1bfd0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1bfe0 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1bff0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1c000 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1c010 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1c020 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1c030 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1c040 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1c050 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1c060 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1c070 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1c080 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1c090 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1c0a0 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1c0b0 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1c0c0 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1c0d0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1c0e0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1c0f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1c100 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1c110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c120 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1c130 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
1c140 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1c150 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1c160 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1c170 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1c180 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1c190 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1c1a0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1c1b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1c1c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1c1d0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1c1e0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1c1f0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1c200 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1c210 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1c220 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1c230 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1c240 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1c250 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1c260 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1c270 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1c280 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1c290 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1c2a0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
1c2b0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
1c2c0 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
1c2d0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
1c2e0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1c2f0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1c300 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1c310 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
1c320 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61  For the limit ca
1c330 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45  tegory of SQLITE
1c340 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65  _LIMIT_XYZ there
1c350 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
1c360 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
1c370 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20  ound].** set by 
1c380 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
1c390 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1c3a0 63 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c  cro named .** [l
1c3b0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
1c3c0 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65  AX_XYZ]..** (The
1c3d0 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
1c3e0 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
1c3f0 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
1c400 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
1c410 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
1c420 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
1c430 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
1c440 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
1c450 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
1c460 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
1c470 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
1c480 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
1c490 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
1c4a0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1c4b0 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
1c4c0 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
1c4d0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
1c4e0 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
1c4f0 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
1c500 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
1c510 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
1c520 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
1c530 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
1c540 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
1c550 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1c560 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1c570 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1c580 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1c590 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1c5a0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1c5b0 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1c5c0 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1c5d0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1c5e0 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1c5f0 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1c600 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1c610 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1c620 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1c630 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1c640 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1c650 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1c660 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1c670 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1c680 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1c690 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1c6a0 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1c6b0 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1c6c0 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1c6d0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1c6e0 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1c6f0 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1c700 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1c710 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1c720 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1c730 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1c740 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1c750 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1c760 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1c770 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1c780 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1c790 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
1c7a0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
1c7b0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
1c7c0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
1c7d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1c7e0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1c7f0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1c800 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1c810 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1c820 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
1c830 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
1c840 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
1c850 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1c860 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1c870 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1c880 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
1c890 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
1c8a0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
1c8b0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
1c8c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1c8d0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
1c8e0 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
1c8f0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
1c900 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
1c910 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
1c920 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
1c930 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
1c940 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
1c950 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
1c960 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
1c970 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c980 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
1c990 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1c9a0 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
1c9b0 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
1c9c0 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 29   table row.<dd>)
1c9d0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1c9e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1c9f0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1ca00 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1ca10 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
1ca20 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
1ca30 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
1ca40 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1ca50 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
1ca60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1ca70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
1ca80 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
1ca90 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
1caa0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
1cab0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
1cac0 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
1cad0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1cae0 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
1caf0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
1cb00 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
1cb10 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
1cb20 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cb30 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1cb40 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1cb50 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
1cb60 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
1cb70 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
1cb80 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
1cb90 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1cba0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1cbb0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
1cbc0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1cbd0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
1cbe0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
1cbf0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
1cc00 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1cc10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
1cc20 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
1cc30 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1cc40 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
1cc50 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
1cc60 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
1cc70 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
1cc80 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
1cc90 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
1cca0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1ccb0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1ccc0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
1ccd0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1cce0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
1ccf0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
1cd00 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1cd10 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1cd20 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
1cd30 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1cd40 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
1cd50 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
1cd60 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
1cd70 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1cd80 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1cd90 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
1cda0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1cdb0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1cdc0 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
1cdd0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
1cde0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
1cdf0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
1ce00 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1ce10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1ce20 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1ce30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1ce40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
1ce50 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
1ce60 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1ce70 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
1ce80 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1ce90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1cea0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
1ceb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1cec0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1ced0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
1cee0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
1cef0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1cf00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1cf10 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1cf20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
1cf30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1cf40 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
1cf50 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
1cf60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1cf70 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
1cf80 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
1cf90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1cfa0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
1cfb0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
1cfc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1cfd0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1cfe0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
1cff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1d000 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
1d010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
1d020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d030 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1d040 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
1d050 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
1d060 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
1d070 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d080 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
1d090 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1d0a0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
1d0b0 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
1d0c0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1d0d0 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
1d0e0 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
1d0f0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1d100 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1d110 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
1d120 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1d130 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1d140 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1d150 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
1d160 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
1d170 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
1d180 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
1d190 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
1d1a0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
1d1b0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
1d1c0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
1d1d0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1d1e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1d1f0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
1d200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d210 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
1d220 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
1d230 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1d240 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1d250 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1d260 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
1d270 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1d280 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
1d290 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
1d2a0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
1d2b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
1d2c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
1d2d0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
1d2e0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1d2f0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1d300 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1d310 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1d320 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1d330 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1d340 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1d350 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1d360 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
1d370 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1d380 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1d390 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1d3a0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1d3b0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
1d3c0 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1d3d0 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1d3e0 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1d3f0 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1d400 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1d410 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
1d420 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1d430 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
1d440 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
1d450 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
1d460 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
1d470 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1d480 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
1d490 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
1d4a0 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
1d4b0 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
1d4c0 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
1d4d0 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
1d4e0 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
1d4f0 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
1d500 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
1d510 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
1d520 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
1d530 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
1d540 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
1d550 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
1d560 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
1d570 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
1d580 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
1d590 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
1d5a0 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
1d5b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1d5c0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
1d5d0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
1d5e0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
1d5f0 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
1d600 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  es..**.** ^If pz
1d610 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1d620 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1d630 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1d640 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
1d650 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
1d660 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
1d670 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1d680 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
1d690 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
1d6a0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
1d6b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1d6c0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
1d6d0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1d6e0 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
1d6f0 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
1d700 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
1d710 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1d720 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1d730 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d740 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1d750 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1d760 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1d770 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
1d780 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1d790 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1d7a0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
1d7b0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
1d7c0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
1d7d0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
1d7e0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
1d7f0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
1d800 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
1d810 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
1d820 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
1d830 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1d840 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
1d850 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
1d860 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1d870 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1d880 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
1d890 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1d8a0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
1d8b0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
1d8c0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
1d8d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
1d8e0 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
1d8f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d900 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
1d910 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
1d920 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1d930 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1d940 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1d950 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
1d960 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1d970 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
1d980 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
1d990 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
1d9a0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
1d9b0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
1d9c0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
1d9d0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1d9e0 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
1d9f0 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
1da00 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
1da10 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1da20 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
1da30 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
1da40 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
1da50 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1da60 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
1da70 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
1da80 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
1da90 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
1daa0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
1dab0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
1dac0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
1dad0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
1dae0 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
1daf0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
1db00 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
1db10 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
1db20 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
1db30 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
1db40 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
1db50 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
1db60 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
1db70 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
1db80 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1db90 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
1dba0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
1dbb0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
1dbc0 20 20 5e 49 66 20 74 68 65 20 73 63 68 65 6d 61    ^If the schema
1dbd0 20 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a   has changed in.
1dbe0 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61  ** a way that ma
1dbf0 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e  kes the statemen
1dc00 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69  t no longer vali
1dc10 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  d, [sqlite3_step
1dc20 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a  ()] will still.*
1dc30 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1dc40 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75  _SCHEMA].  But u
1dc50 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79  nlike the legacy
1dc60 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49   behavior, [SQLI
1dc70 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a  TE_SCHEMA] is.**
1dc80 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72   now a fatal err
1dc90 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71  or.  Calling [sq
1dca0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dcb0 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e  ()] again will n
1dcc0 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65  ot make the.** e
1dcd0 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e  rror go away.  N
1dce0 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65  ote: use [sqlite
1dcf0 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66  3_errmsg()] to f
1dd00 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20  ind the text.** 
1dd10 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65  of the parsing e
1dd20 72 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74  rror that result
1dd30 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  s in an [SQLITE_
1dd40 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a  SCHEMA] return..
1dd50 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
1dd60 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
1dd70 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
1dd80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1dd90 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
1dda0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
1ddb0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
1ddc0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
1ddd0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
1dde0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1ddf0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1de00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1de10 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1de20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1de30 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1de40 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
1de50 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
1de60 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
1de70 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
1de80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1de90 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
1dea0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
1deb0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
1dec0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
1ded0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
1dee0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
1def0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
1df00 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
1df10 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1df20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
1df30 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1df40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
1df50 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65  e of a [paramete
1df60 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
1df70 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45  er] in the WHERE
1df80 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a   clause might.**
1df90 20 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72   change the quer
1dfa0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
1dfb0 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  tement, then the
1dfc0 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62   statement may b
1dfd0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1dfe0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61  ly recompiled (a
1dff0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
1e000 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61  een a schema cha
1e010 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73  nge) on the firs
1e020 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  t .** [sqlite3_s
1e030 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
1e040 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
1e050 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
1e060 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1e070 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
1e080 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  e [parameter]. .
1e090 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1e0a0 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1e0b0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1e0c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1e0d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1e0e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e0f0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1e100 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1e110 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1e120 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1e130 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1e140 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1e150 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1e160 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1e170 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1e180 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1e190 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1e1a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1e1b0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1e1c0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1e1d0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1e1e0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1e1f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1e200 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1e210 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1e220 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1e230 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1e240 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1e250 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1e260 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1e270 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1e280 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1e290 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1e2a0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1e2b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1e2c0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1e2d0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1e2e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1e2f0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1e300 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1e310 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1e320 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1e330 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1e340 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1e350 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1e360 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1e370 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1e380 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1e390 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1e3a0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1e3b0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1e3c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1e3d0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1e3e0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1e3f0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1e400 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1e410 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1e420 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1e430 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1e440 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1e450 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1e460 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1e470 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1e480 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1e490 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1e4a0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1e4b0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1e4c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1e4d0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1e4e0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1e4f0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1e500 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1e510 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1e520 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1e530 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1e540 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1e550 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1e560 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1e570 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1e580 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1e590 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1e5a0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1e5b0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1e5c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1e5d0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1e5e0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
1e5f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1e600 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
1e610 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
1e620 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
1e630 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
1e640 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
1e650 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e660 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
1e670 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
1e680 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1e690 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1e6a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1e6b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e6c0 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
1e6d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1e6e0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1e6f0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1e700 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1e710 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1e720 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1e730 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
1e740 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
1e750 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1e760 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
1e770 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
1e780 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e790 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
1e7a0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
1e7b0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
1e7c0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
1e7d0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
1e7e0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
1e7f0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
1e800 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
1e810 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
1e820 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1e830 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
1e840 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
1e850 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
1e860 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
1e870 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
1e880 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
1e890 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
1e8a0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
1e8b0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
1e8c0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
1e8d0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1e8e0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
1e8f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
1e900 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
1e910 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
1e920 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
1e930 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
1e940 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1e950 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
1e960 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
1e970 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
1e980 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
1e990 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
1e9a0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
1e9b0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
1e9c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1e9d0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
1e9e0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
1e9f0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
1ea00 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
1ea10 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
1ea20 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
1ea30 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
1ea40 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
1ea50 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1ea60 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
1ea70 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1ea80 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1ea90 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1eaa0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
1eab0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1eac0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
1ead0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
1eae0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1eaf0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
1eb00 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1eb10 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
1eb20 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
1eb30 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
1eb40 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
1eb50 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
1eb60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
1eb70 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
1eb80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
1eb90 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
1eba0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
1ebb0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1ebc0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1ebd0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1ebe0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1ebf0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
1ec00 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
1ec10 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
1ec20 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
1ec30 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1ec40 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
1ec50 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
1ec60 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
1ec70 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
1ec80 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
1ec90 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1eca0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1ecb0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1ecc0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
1ecd0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
1ece0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ecf0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1ed00 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
1ed10 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
1ed20 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
1ed30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1ed40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1ed50 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1ed60 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
1ed70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1ed80 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
1ed90 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
1eda0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
1edb0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
1edc0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
1edd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ede0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
1edf0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
1ee00 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
1ee10 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
1ee20 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
1ee30 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
1ee40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
1ee50 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
1ee60 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
1ee70 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
1ee80 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
1ee90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1eea0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
1eeb0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1eec0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
1eed0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
1eee0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
1eef0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
1ef00 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
1ef10 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
1ef20 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
1ef30 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
1ef40 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
1ef50 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
1ef60 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
1ef70 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1ef80 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
1ef90 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
1efa0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
1efb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
1efc0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
1efd0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
1efe0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1eff0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
1f000 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
1f010 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
1f020 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
1f030 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1f040 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
1f050 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
1f060 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
1f070 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
1f080 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
1f090 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
1f0a0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
1f0b0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
1f0c0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
1f0d0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
1f0e0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
1f0f0 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
1f100 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
1f110 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
1f120 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
1f130 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
1f140 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
1f150 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
1f160 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
1f170 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
1f180 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
1f190 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1f1a0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
1f1b0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
1f1c0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
1f1d0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
1f1e0 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  ding}.**.** ^(In
1f1f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f200 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
1f210 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f220 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
1f230 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
1f240 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
1f250 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
1f260 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
1f270 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
1f280 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
1f290 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
1f2a0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
1f2b0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
1f2c0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
1f2d0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
1f2e0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
1f2f0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
1f300 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
1f310 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
1f320 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
1f330 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
1f340 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
1f350 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
1f360 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
1f370 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
1f380 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
1f390 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
1f3a0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
1f3b0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
1f3c0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
1f3d0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f3e0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
1f3f0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
1f400 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1f410 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
1f420 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1f430 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
1f440 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1f450 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1f460 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
1f470 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
1f480 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f490 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1f4a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
1f4b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
1f4c0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
1f4d0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
1f4e0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
1f4f0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
1f500 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1f510 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
1f520 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
1f530 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
1f540 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
1f550 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
1f560 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
1f570 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
1f580 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
1f590 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
1f5a0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
1f5b0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
1f5c0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
1f5d0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
1f5e0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
1f5f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1f600 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
1f610 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
1f620 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
1f630 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
1f640 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
1f650 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
1f660 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
1f670 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
1f680 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
1f690 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
1f6a0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
1f6b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1f6c0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
1f6d0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
1f6e0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
1f6f0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
1f700 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
1f710 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1f720 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
1f730 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
1f740 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
1f750 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
1f760 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
1f770 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
1f780 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
1f790 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
1f7a0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
1f7b0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
1f7c0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
1f7d0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
1f7e0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
1f7f0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
1f800 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
1f810 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
1f820 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
1f830 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
1f840 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
1f850 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
1f860 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
1f870 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
1f880 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1f890 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
1f8a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
1f8b0 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
1f8c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
1f8d0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
1f8e0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
1f8f0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
1f900 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
1f910 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
1f920 68 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49 66  hed with it. ^If
1f930 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1f940 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
1f950 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
1f960 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
1f970 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
1f980 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
1f990 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
1f9a0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
1f9b0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
1f9c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
1f9d0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
1f9e0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
1f9f0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
1fa00 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
1fa10 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
1fa20 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
1fa30 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
1fa40 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
1fa50 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
1fa60 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1fa70 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
1fa80 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
1fa90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
1faa0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
1fab0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
1fac0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
1fad0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
1fae0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
1faf0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
1fb00 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
1fb10 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
1fb20 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
1fb30 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
1fb40 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
1fb50 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
1fb60 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
1fb70 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
1fb80 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
1fb90 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
1fba0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
1fbb0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
1fbc0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
1fbd0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
1fbe0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
1fbf0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
1fc00 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
1fc10 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
1fc20 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
1fc30 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
1fc40 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
1fc50 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1fc60 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
1fc70 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1fc80 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
1fc90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1fca0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
1fcb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fcc0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
1fcd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fce0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
1fcf0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
1fd00 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
1fd10 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
1fd20 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
1fd30 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
1fd40 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
1fd50 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
1fd60 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
1fd70 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
1fd80 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
1fd90 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
1fda0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
1fdb0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
1fdc0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
1fdd0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
1fde0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
1fdf0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
1fe00 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
1fe10 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
1fe20 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1fe30 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
1fe40 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
1fe50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
1fe60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
1fe70 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
1fe80 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
1fe90 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
1fea0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
1feb0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
1fec0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
1fed0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
1fee0 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
1fef0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
1ff00 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
1ff10 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
1ff20 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
1ff30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1ff40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ff50 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
1ff60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ff70 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1ff80 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1ff90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1ffa0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
1ffb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1ffc0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
1ffd0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
1ffe0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
1fff0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
20000 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
20010 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
20020 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
20030 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
20040 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
20050 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
20060 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20070 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
20080 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
20090 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
200a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
200b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
200c0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
200d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
200e0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
200f0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
20100 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
20110 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
20120 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
20130 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
20140 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
20150 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
20160 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
20170 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
20180 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
20190 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
201a0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
201b0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
201c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
201d0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
201e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
201f0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
20200 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
20210 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
20220 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
20230 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
20240 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
20250 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
20260 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
20270 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
20280 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
20290 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
202a0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
202b0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
202c0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
202d0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
202e0 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
202f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20300 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
20310 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
20320 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
20330 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
20340 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
20350 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
20360 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
20370 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
20380 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
20390 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
203a0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
203b0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
203c0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
203d0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
203e0 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
203f0 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
20400 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
20410 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
20420 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
20430 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
20440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
20450 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
20460 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
20470 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
20480 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
20490 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
204a0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
204b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
204c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
204d0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
204e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
204f0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
20500 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
20510 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20520 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
20530 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
20540 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
20550 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
20560 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
20570 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
20580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
20590 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
205a0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
205b0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
205c0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
205d0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
205e0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
205f0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
20600 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
20610 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
20620 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
20630 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
20640 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
20650 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
20660 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
20670 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
20680 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
20690 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
206a0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
206b0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
206c0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
206d0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
206e0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
206f0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
20700 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
20710 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
20720 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
20730 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
20740 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
20750 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
20760 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
20770 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
20780 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
20790 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
207a0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
207b0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
207c0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
207d0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
207e0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
207f0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
20800 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
20810 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
20820 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
20830 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20840 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
20850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
20860 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
20870 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
20880 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
20890 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
208a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
208b0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
208c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
208d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
208e0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
208f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
20900 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
20910 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
20920 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
20930 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
20940 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
20950 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
20960 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
20970 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
20980 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
20990 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
209a0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
209b0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
209c0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
209d0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
209e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
209f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
20a00 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
20a10 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
20a20 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
20a30 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
20a40 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
20a50 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
20a60 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
20a70 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
20a80 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
20a90 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
20aa0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
20ab0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
20ac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20ad0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
20ae0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
20af0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
20b00 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
20b10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20b20 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
20b30 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
20b40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
20b50 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
20b60 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20b70 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
20b80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
20b90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
20ba0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20bb0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
20bc0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
20bd0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
20be0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
20bf0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
20c00 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
20c10 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
20c20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
20c30 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20c40 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
20c50 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
20c60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
20c70 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
20c80 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
20c90 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
20ca0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
20cb0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
20cc0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
20cd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20ce0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
20cf0 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
20d00 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
20d10 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
20d20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
20d30 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
20d40 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
20d50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20d60 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
20d70 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
20d80 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
20d90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
20da0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
20db0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
20dc0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
20dd0 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
20de0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
20df0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
20e00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
20e10 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
20e20 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
20e30 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
20e40 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
20e50 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
20e60 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
20e70 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
20e80 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
20e90 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
20ea0 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
20eb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
20ec0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
20ed0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
20ee0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
20ef0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
20f00 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
20f10 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
20f20 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
20f30 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
20f40 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
20f50 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
20f60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
20f70 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
20f80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
20f90 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
20fa0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
20fb0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
20fc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
20fd0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
20fe0 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
20ff0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
21000 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
21010 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
21020 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
21030 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
21040 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
21050 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
21060 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
21070 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
21080 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
21090 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
210a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
210b0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
210c0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
210d0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
210e0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
210f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21100 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
21110 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
21120 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
21130 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
21140 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
21150 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
21160 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
21170 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
21180 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
21190 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
211a0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
211b0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
211c0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
211d0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
211e0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
211f0 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
21200 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
21210 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
21220 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21230 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
21240 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
21250 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
21260 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
21270 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
21280 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
21290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
212a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
212b0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
212c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
212d0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
212e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
212f0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
21300 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
21310 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
21320 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
21330 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
21340 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
21350 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
21360 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
21370 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
21380 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
21390 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
213a0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
213b0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
213c0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
213d0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
213e0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
213f0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
21400 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
21410 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
21420 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
21430 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
21440 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
21450 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
21460 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
21470 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
21480 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
21490 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
214a0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
214b0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
214c0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
214d0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
214e0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
214f0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
21500 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
21510 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
21520 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21530 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
21540 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
21550 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
21560 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
21570 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
21580 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
21590 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
215a0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
215b0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
215c0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
215d0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
215e0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
215f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
21600 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
21610 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
21620 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
21630 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
21640 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
21650 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
21660 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
21670 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
21680 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
21690 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
216a0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
216b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
216c0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
216d0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
216e0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
216f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
21700 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
21710 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
21720 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
21730 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
21740 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
21750 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
21760 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
21770 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
21780 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
21790 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
217a0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
217b0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
217c0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
217d0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
217e0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
217f0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
21800 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
21810 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
21820 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
21830 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
21840 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
21850 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
21860 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
21870 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
21880 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
21890 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
218a0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
218b0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
218c0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
218d0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
218e0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
218f0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
21900 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
21910 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
21920 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
21930 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
21940 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
21950 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
21960 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
21970 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
21980 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
21990 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
219a0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
219b0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
219c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
219d0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
219e0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
219f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
21a00 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
21a10 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
21a20 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
21a30 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
21a40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
21a50 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
21a60 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
21a70 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
21a80 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
21a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
21aa0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
21ab0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
21ac0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
21ad0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
21ae0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
21af0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
21b00 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
21b10 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
21b20 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
21b30 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
21b40 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
21b50 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21b60 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
21b70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21b80 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
21b90 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
21ba0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
21bb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
21bc0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
21bd0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
21be0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
21bf0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
21c00 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
21c10 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
21c20 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
21c30 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
21c40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
21c50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
21c60 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
21c70 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
21c80 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
21c90 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
21ca0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
21cb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
21cc0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
21cd0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
21ce0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
21cf0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
21d00 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
21d10 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
21d20 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
21d30 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
21d40 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
21d50 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
21d60 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
21d70 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
21d80 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
21d90 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
21da0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
21db0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
21dc0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
21dd0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
21de0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
21df0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
21e00 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
21e10 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
21e20 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
21e30 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
21e40 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
21e50 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
21e60 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
21e70 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
21e80 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
21e90 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
21ea0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
21eb0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
21ec0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
21ed0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
21ee0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
21ef0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
21f00 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
21f10 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
21f20 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
21f30 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
21f40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21f50 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
21f60 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
21f70 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
21f80 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
21f90 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
21fa0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
21fb0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
21fc0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
21fd0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
21fe0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
21ff0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
22000 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
22010 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
22020 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
22030 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
22040 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
22050 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
22060 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
22070 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
22080 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
22090 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
220a0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
220b0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
220c0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
220d0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
220e0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
220f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22100 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
22110 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
22120 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
22130 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
22140 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22150 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
22160 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
22170 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
22180 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
22190 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
221a0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
221b0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
221c0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
221d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
221e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
221f0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
22200 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
22210 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
22220 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
22230 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
22240 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
22250 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
22260 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
22270 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
22280 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
22290 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
222a0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
222b0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
222c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
222d0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
222e0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
222f0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
22300 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
22310 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
22320 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
22330 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22340 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
22350 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
22360 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
22370 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
22380 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22390 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
223a0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
223b0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
223c0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
223d0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
223e0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
223f0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
22400 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
22410 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
22420 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
22430 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
22440 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
22450 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
22460 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
22470 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
22480 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
22490 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
224a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
224b0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
224c0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
224d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
224e0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
224f0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
22500 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
22510 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
22520 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
22530 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
22540 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
22550 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
22560 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
22570 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
22580 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
22590 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
225a0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
225b0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
225c0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
225d0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
225e0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
225f0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
22600 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
22610 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
22620 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
22630 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
22640 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
22650 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
22660 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
22670 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
22680 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
22690 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
226a0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
226b0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
226c0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
226d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
226e0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
226f0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
22700 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
22710 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
22720 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
22730 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
22740 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
22750 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
22760 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
22770 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
22780 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
22790 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
227a0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
227b0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
227c0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
227d0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
227e0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
227f0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
22800 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
22810 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
22820 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
22830 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
22840 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
22850 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
22860 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
22870 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
22880 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
22890 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
228a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
228b0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
228c0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
228d0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
228e0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
228f0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
22900 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
22910 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
22920 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
22930 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
22940 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
22950 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
22960 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
22970 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
22980 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
22990 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
229a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
229b0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
229c0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
229d0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
229e0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
229f0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
22a00 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
22a10 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
22a20 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
22a30 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
22a40 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
22a50 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
22a60 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
22a70 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
22a80 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
22a90 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
22aa0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
22ab0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
22ac0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
22ad0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
22ae0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
22af0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
22b00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
22b10 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
22b20 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
22b30 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
22b40 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
22b50 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
22b60 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
22b70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
22b80 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
22b90 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
22ba0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
22bb0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
22bc0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
22bd0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
22be0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
22bf0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
22c00 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
22c10 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
22c20 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
22c30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
22c40 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
22c50 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
22c60 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
22c70 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
22c80 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
22c90 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
22ca0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
22cb0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
22cc0 2c 20 69 74 20 77 61 73 20 72 65 71 75 69 72 65  , it was require
22cd0 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69 74  d.** after sqlit
22ce0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
22cf0 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65  ed anything othe
22d00 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
22d10 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  OW] that.** [sql
22d20 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62 65  ite3_reset()] be
22d30 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 61   called before a
22d40 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
22d50 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
22d60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
22d70 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f 6b  Failure to invok
22d80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
22d90 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79 20  ()] in this way 
22da0 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74 20  would.** result 
22db0 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
22dc0 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
22dd0 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  m sqlite3_step()
22de0 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a 20  .  But after.** 
22df0 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
22e00 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
22e10 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20 5b   began calling [
22e20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22e30 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c   .** automatical
22e40 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
22e50 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 20 74  mstance rather t
22e60 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
22e70 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
22e80 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
22e90 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
22ea0 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
22eb0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
22ec0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
22ed0 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
22ee0 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
22ef0 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
22f00 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
22f10 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
22f20 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
22f30 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
22f40 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
22f50 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
22f60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
22f70 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
22f80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
22f90 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
22fa0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
22fb0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
22fc0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
22fd0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
22fe0 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
22ff0 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
23000 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
23010 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
23020 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
23030 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
23040 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
23050 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
23060 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
23070 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
23080 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23090 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
230a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
230b0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
230c0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
230d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
230e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
230f0 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
23100 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
23110 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
23120 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
23130 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
23140 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
23150 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
23160 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
23170 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
23180 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74  ommended..*/.int
23190 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
231a0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
231b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
231c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
231d0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
231e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
231f0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
23200 29 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  ) the number of 
23210 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
23220 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
23230 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
23240 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
23250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
23260 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
23270 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
23280 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23290 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
232a0 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
232b0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
232c0 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
232d0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
232e0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
232f0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
23300 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
23310 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
23320 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
23330 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
23340 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
23350 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
23360 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
23370 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
23380 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
23390 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
233a0 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
233b0 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
233c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
233d0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
233e0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
233f0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
23400 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
23410 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
23420 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
23430 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
23440 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
23450 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
23460 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
23470 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
23480 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
23490 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
234a0 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
234b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
234c0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
234d0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
234e0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
234f0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
23500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
23510 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
23520 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
23530 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
23540 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
23550 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
23560 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
23570 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
23580 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
23590 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
235a0 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
235b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
235c0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
235d0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
235e0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
235f0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
23600 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
23610 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
23620 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
23630 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
23640 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
23650 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
23660 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
23670 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
23680 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
23690 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
236a0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
236b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
236c0 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
236d0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
236e0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
236f0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
23700 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
23710 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
23720 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
23730 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
23740 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
23750 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
23760 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
23770 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
23780 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
23790 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
237a0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
237b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
237c0 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
237d0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
237e0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
237f0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
23800 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
23810 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
23820 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
23830 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
23840 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
23850 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
23860 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
23870 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
23880 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
23890 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
238a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
238b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
238c0 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
238d0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
238e0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
238f0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
23900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
23910 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
23920 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
23930 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
23940 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
23950 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
23960 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
23970 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
23980 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
23990 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
239a0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
239b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
239c0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
239d0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
239e0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
239f0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
23a00 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
23a10 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
23a20 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
23a30 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
23a40 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
23a50 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
23a60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
23a70 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
23a80 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
23a90 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
23aa0 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
23ab0 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
23ac0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
23ad0 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
23ae0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
23af0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
23b00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
23b10 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
23b20 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
23b30 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
23b40 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
23b50 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
23b60 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
23b70 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
23b80 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
23b90 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
23ba0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
23bb0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
23bc0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
23bd0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
23be0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
23bf0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
23c00 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
23c10 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
23c20 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
23c30 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
23c40 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
23c50 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
23c60 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
23c70 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
23c80 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
23c90 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
23ca0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
23cb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
23cc0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
23cd0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
23ce0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
23cf0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
23d00 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
23d10 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
23d20 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
23d30 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
23d40 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
23d50 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
23d60 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
23d70 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
23d80 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
23d90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
23da0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
23db0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
23dc0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
23dd0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
23de0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
23df0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
23e00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
23e10 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
23e20 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
23e30 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
23e40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
23e50 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
23e60 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
23e70 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
23e80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23e90 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
23ea0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
23eb0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
23ec0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
23ed0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
23ee0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
23ef0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
23f00 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
23f10 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
23f20 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
23f30 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
23f40 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
23f50 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
23f60 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
23f70 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20  rity: the value 
23f80 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20  returned is the 
23f90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
23fa0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
23fb0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
23fc0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
23fd0 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
23fe0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
23ff0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
24000 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
24010 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
24020 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
24030 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
24040 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
24050 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
24060 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
24070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
24080 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
24090 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61  gth BLOB is an a
240a0 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e  rbitrary.** poin
240b0 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76  ter, possibly ev
240c0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
240d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
240e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
240f0 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
24100 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
24110 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24120 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
24130 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
24140 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
24150 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
24160 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
24170 20 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69   ^The zero termi
24180 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63  nator is not inc
24190 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f  luded in this co
241a0 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  unt..**.** ^The 
241b0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
241c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
241d0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
241e0 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
241f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
24200 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
24210 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24220 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
24230 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
24240 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
24250 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
24260 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
24270 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
24280 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
24290 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
242a0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
242b0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
242c0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
242d0 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
242e0 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
242f0 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
24300 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
24310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
24320 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
24330 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
24340 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
24350 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
24360 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
24370 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
24380 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
24390 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
243a0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
243b0 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
243c0 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
243d0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
243e0 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
243f0 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
24400 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
24410 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
24420 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
24430 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
24440 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
24450 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
24460 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
24470 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
24480 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
24490 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
244a0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
244b0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
244c0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
244d0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
244e0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
244f0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
24500 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
24510 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
24520 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
24530 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
24540 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
24550 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
24560 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
24570 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
24580 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
24590 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
245a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
245b0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
245c0 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
245d0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
245e0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
245f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
24600 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
24610 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
24620 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
24630 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
24640 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
24650 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
24660 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
24670 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
24680 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
24690 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
246a0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
246b0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
246c0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
246d0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
246e0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
246f0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
24700 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
24710 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
24720 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
24730 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
24740 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
24750 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
24760 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
24770 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
24780 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
24790 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
247a0 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
247b0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
247c0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
247d0 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
247e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
247f0 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
24800 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
24810 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
24820 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
24830 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
24840 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
24850 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
24860 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
24870 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
24880 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
24890 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
248a0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
248b0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
248c0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
248d0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
248e0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
248f0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
24900 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
24910 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
24920 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
24930 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
24940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
24950 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
24960 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
24970 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
24980 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
24990 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
249a0 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
249b0 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
249c0 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
249d0 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
249e0 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
249f0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
24a00 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
24a10 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
24a20 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
24a30 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
24a40 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
24a50 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
24a60 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
24a70 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ers..**.** ^Note
24a80 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
24a90 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
24aa0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
24ab0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
24ac0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
24ad0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
24ae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24af0 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
24b00 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
24b10 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
24b20 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
24b30 20 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73 69   ^(Type conversi
24b40 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
24b50 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
24b60 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
24b70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
24b80 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
24b90 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
24ba0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
24bb0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
24bc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
24bd0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
24be0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
24bf0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
24c00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
24c10 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
24c20 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
24c30 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
24c40 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
24c50 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
24c60 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
24c70 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
24c80 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
24c90 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
24ca0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
24cb0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
24cc0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
24cd0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
24ce0 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
24cf0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
24d00 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
24d10 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
24d20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24d30 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
24d40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24d50 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
24d60 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
24d70 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
24d80 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
24d90 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
24da0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  )^.**.** ^Conver
24db0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
24dc0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
24dd0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
24de0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
24df0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
24e00 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
24e10 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
24e20 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
24e30 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
24e40 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
24e50 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e  ior pointer poin
24e60 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20  ts to will have 
24e70 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
24e80 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
24e90 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
24ea0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
24eb0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
24ec0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
24ed0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
24ee0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
24ef0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
24f00 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
24f10 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
24f20 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73 74  .** ^(The safest
24f30 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
24f40 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
24f50 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
24f60 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
24f70 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
24f80 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
24f90 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
24fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24fb0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
24fc0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
24fd0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
24fe0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
24ff0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
25000 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
25010 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
25020 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
25030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
25040 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
25050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25060 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
25070 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49   </ul>)^.**.** I
25080 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
25090 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
250a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
250b0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
250c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
250d0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
250e0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
250f0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
25100 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
25110 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
25120 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
25130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25140 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
25150 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
25160 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
25170 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
25180 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
25190 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
251a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
251b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
251c0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
251d0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
251e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
251f0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
25200 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
25210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
25220 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
25230 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
25240 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
25250 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
25260 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
25270 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
25280 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
25290 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
252a0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
252b0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
252c0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
252d0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
252e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
252f0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
25300 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
25310 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
25320 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
25330 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
25340 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
25350 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
25360 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
25370 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
25380 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
25390 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
253a0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
253b0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
253c0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
253d0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
253e0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
253f0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
25400 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
25410 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
25420 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
25430 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
25440 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
25450 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
25460 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
25470 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
25480 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
25490 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
254a0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
254b0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
254c0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
254d0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
254e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
254f0 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
25500 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
25510 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
25520 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25530 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
25540 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
25550 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
25560 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
25570 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
25580 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25590 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
255a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
255b0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
255c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
255d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
255e0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
255f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25600 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
25610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
25620 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
25630 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
25640 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
25650 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
25660 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
25670 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
25680 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
25690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
256a0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
256b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
256c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
256d0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
256e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
256f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
25700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
25710 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
25720 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
25730 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
25740 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
25750 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
25760 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
25770 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25780 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
25790 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
257a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
257b0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
257c0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65   statement was e
257d0 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66  xecuted successf
257e0 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63  ully or not exec
257f0 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65  uted at all, the
25800 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69  n.** SQLITE_OK i
25810 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66 20  s returned. ^If 
25820 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
25830 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
25840 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72  d then an.** [er
25850 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ror code] or [ex
25860 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
25870 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
25880 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
25890 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
258a0 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
258b0 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  uring the execut
258c0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70  ion of the.** [p
258d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
258e0 74 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69 72  t].  ^If the vir
258f0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73  tual machine has
25900 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   not.** complete
25910 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e  d execution when
25920 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
25930 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73   called, that is
25940 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74   like.** encount
25950 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f  ering an error o
25960 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  r an [sqlite3_in
25970 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
25980 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70  upt]..** ^Incomp
25990 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
259a0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
259b0 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
259c0 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65   canceled,.** de
259d0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
259e0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
259f0 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20  d the.** [error 
25a00 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
25a10 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
25a20 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  BORT]..*/.int sq
25a30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
25a40 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
25a50 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
25a60 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
25a70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
25a80 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
25a90 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
25aa0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
25ab0 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
25ac0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25ad0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
25ae0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
25af0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
25b00 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
25b10 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
25b20 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
25b30 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
25b40 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
25b50 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
25b60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25b70 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
25b80 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
25b90 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
25ba0 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
25bb0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
25bc0 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
25bd0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
25be0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
25bf0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
25c00 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
25c10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25c20 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
25c30 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
25c40 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
25c50 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
25c60 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
25c70 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
25c80 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
25c90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
25ca0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
25cb0 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
25cc0 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
25cd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
25ce0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
25cf0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
25d00 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
25d10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
25d20 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
25d30 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
25d40 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
25d50 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25d60 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
25d70 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
25d80 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
25d90 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
25da0 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
25db0 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
25dc0 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
25dd0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
25de0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
25df0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
25e00 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
25e10 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
25e20 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
25e30 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
25e40 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
25e50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25e60 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
25e70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
25e80 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
25e90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25ea0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
25eb0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
25ec0 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
25ed0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
25ee0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
25ef0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
25f00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25f10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
25f20 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
25f30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25f40 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
25f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77  .**.** ^These tw
25f60 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
25f70 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
25f80 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
25f90 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
25fa0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
25fb0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
25fc0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
25fd0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
25fe0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
25ff0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
26000 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
26010 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
26020 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  y difference bet
26030 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20  ween the.** two 
26040 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
26050 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
26060 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73  e name of the (s
26070 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20  calar) function 
26080 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c  or.** aggregate,
26090 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
260a0 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33  TF-8 for sqlite3
260b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
260c0 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a  () and UTF-16.**
260d0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
260e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
260f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
26100 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
26110 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
26120 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
26130 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
26140 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
26150 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
26160 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
26170 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
26180 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
26190 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
261a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
261b0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
261c0 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
261d0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
261e0 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
261f0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
26200 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
26210 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
26220 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
26230 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
26240 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
26250 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
26260 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
26270 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
26280 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a   exclusive of.**
26290 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
262a0 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
262b0 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
262c0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
262d0 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
262e0 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74  cters.  ^Any att
262f0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
26300 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
26310 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
26320 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
26330 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65  SQLITE_ERROR] be
26340 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
26350 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
26360 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
26370 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
26380 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
26390 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
263a0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
263b0 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
263c0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
263d0 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
263e0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
263f0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
26400 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
26410 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
26420 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
26430 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
26440 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
26450 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26460 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
26470 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
26480 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
26490 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
264a0 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
264b0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
264c0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
264d0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
264e0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
264f0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
26500 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
26510 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
26520 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
26530 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
26540 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
26550 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
26560 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
26570 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
26580 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
26590 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
265a0 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
265b0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
265c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
265d0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
265e0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
265f0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
26600 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
26610 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
26620 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
26630 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
26640 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
26650 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
26660 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
26670 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
26680 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
26690 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
266a0 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
266b0 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
266c0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
266d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
266e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
266f0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
26700 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
26710 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
26720 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
26730 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
26740 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
26750 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
26760 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
26770 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
26780 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
26790 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
267a0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
267b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
267c0 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
267d0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
267e0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
267f0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
26800 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
26810 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
26820 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
26830 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
26840 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
26850 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
26860 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
26870 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  )^.**.** The sev
26880 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
26890 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
268a0 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
268b0 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
268c0 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
268d0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
268e0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
268f0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
26900 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
26910 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
26920 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
26930 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
26940 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
26950 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
26960 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
26970 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
26980 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
26990 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
269a0 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
269b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
269c0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
269d0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
269e0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
269f0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
26a00 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
26a10 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
26a20 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
26a30 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
26a40 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
26a50 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72  e, pass NULL for
26a60 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
26a70 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  ion callbacks..*
26a80 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
26a90 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
26aa0 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
26ab0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
26ac0 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
26ad0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
26ae0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
26af0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
26b00 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
26b10 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
26b20 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
26b30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
26b40 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
26b50 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
26b60 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
26b70 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
26b80 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
26b90 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
26ba0 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
26bb0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
26bc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
26bd0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
26be0 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
26bf0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
26c00 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
26c10 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
26c20 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
26c30 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
26c40 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
26c50 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
26c60 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
26c70 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
26c80 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
26c90 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
26ca0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
26cb0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
26cc0 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
26cd0 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
26ce0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
26cf0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
26d00 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
26d10 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
26d20 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
26d30 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
26d40 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
26d50 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
26d60 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
26d70 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
26d80 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
26d90 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
26da0 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
26db0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
26dc0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26dd0 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  s..** ^The first
26de0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
26df0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69  ined function wi
26e00 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20  th a given name 
26e10 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a  overrides all.**
26e20 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69   built-in functi
26e30 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20  ons in the same 
26e40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26e50 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73  tion] with the s
26e60 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75  ame name..** ^Su
26e70 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61  bsequent applica
26e80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26e90 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ctions of the sa
26ea0 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65  me name only ove
26eb0 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20  rride .** prior 
26ec0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26ed0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ned functions th
26ee0 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20  at are an exact 
26ef0 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a  match for the.**
26f00 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
26f10 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72  eters and prefer
26f20 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  red encoding..**
26f30 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
26f40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
26f50 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
26f60 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
26f70 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
26f80 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
26f90 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
26fa0 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
26fb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26fc0 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
26fd0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
26fe0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
26ff0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
27000 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
27010 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
27020 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
27030 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
27040 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
27050 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
27060 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
27070 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
27080 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
27090 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
270a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
270b0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
270c0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
270d0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
270e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
270f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
27100 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
27110 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
27120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
27130 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
27140 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
27150 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
27160 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
27170 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
27180 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
27190 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
271a0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
271b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
271c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
271d0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
271e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
271f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
27200 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
27210 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
27220 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
27230 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
27240 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
27250 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
27260 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
27270 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
27280 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
27290 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
272a0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
272b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
272c0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
272d0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
272e0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
272f0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
27300 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
27310 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
27320 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
27330 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
27340 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
27350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
27360 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
27370 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
27380 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
27390 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
273a0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
273b0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
273c0 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
273d0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
273e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
273f0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
27400 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
27410 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
27420 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
27430 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
27440 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
27450 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
27460 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
27470 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
27480 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
27490 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
274a0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
274b0 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
274c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
274d0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
274e0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
274f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
27500 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
27510 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
27520 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
27530 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
27540 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
27550 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
27560 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
27570 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
27580 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
27590 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
275a0 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
275b0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
275c0 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
275d0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
275e0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
275f0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
27600 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
27610 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
27620 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
27630 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
27640 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
27650 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
27660 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
27670 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
27680 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
27690 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
276a0 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50  CATED.SQLITE_DEP
276b0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
276c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
276d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
276e0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  ext*);.SQLITE_DE
276f0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
27700 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
27710 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
27720 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
27730 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
27740 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
27750 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
27760 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
27770 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
27780 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
27790 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
277a0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
277b0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74  D void sqlite3_t
277c0 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f  hread_cleanup(vo
277d0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
277e0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
277f0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
27800 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
27810 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
27820 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  ,void*,sqlite3_i
27830 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
27840 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
27850 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
27860 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
27870 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
27880 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
27890 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
278a0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
278b0 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
278c0 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
278d0 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
278e0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
278f0 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
27900 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
27910 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
27920 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
27930 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
27940 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
27950 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
27960 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
27970 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
27980 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
27990 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
279a0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
279b0 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
279c0 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
279d0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
279e0 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
279f0 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74  gates..** The 4t
27a00 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
27a10 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
27a20 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
27a30 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
27a40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27a50 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
27a60 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
27a70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27a80 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
27a90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
27aa0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
27ab0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27ac0 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
27ad0 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
27ae0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
27af0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
27b00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
27b10 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
27b20 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
27b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
27b40 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
27b50 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
27b60 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
27b70 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
27b80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
27b90 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
27ba0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
27bb0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
27bc0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
27bd0 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
27be0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
27bf0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
27c00 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
27c10 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
27c20 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
27c30 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
27c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
27c50 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
27c60 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
27c70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
27c80 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
27c90 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
27ca0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
27cb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27cc0 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
27cd0 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
27ce0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
27cf0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
27d00 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
27d10 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
27d20 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
27d30 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
27d40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27d50 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
27d60 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
27d70 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
27d80 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
27d90 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
27da0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
27db0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
27dc0 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
27dd0 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
27de0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
27df0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
27e00 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
27e10 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
27e20 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
27e30 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
27e40 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
27e50 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
27e60 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
27e70 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
27e80 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
27e90 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
27ea0 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
27eb0 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
27ec0 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
27ed0 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
27ee0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
27ef0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
27f00 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
27f10 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
27f20 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
27f30 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
27f40 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
27f50 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
27f60 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
27f70 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
27f80 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
27f90 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
27fa0 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
27fb0 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
27fc0 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
27fd0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
27fe0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
27ff0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28000 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
28010 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
28020 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
28030 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
28040 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
28050 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
28060 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
28070 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
28080 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
28090 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
280a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
280b0 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
280c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
280d0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
280e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
280f0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
28100 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
28110 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
28120 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
28130 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
28140 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28150 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
28160 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28170 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28180 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
28190 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
281a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
281b0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
281c0 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
281d0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
281e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
281f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
28200 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
28210 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
28220 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
28230 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
28240 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
28250 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
28260 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
28270 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
28280 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
28290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
282a0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
282b0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
282c0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
282d0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
282e0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
282f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
28300 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
28310 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
28320 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
28330 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
28340 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
28350 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
28360 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
28370 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
28380 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
28390 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
283a0 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
283b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
283c0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
283d0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
283e0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
283f0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
28400 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
28410 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
28420 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
28430 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
28440 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
28450 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
28460 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
28470 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
28480 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
28490 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
284a0 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
284b0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
284c0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
284d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
284e0 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
284f0 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
28500 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
28510 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
28520 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
28530 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
28540 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
28550 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
28560 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
28570 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
28580 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
28590 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
285a0 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
285b0 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
285c0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
285d0 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
285e0 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
285f0 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
28600 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
28610 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
28620 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
28630 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
28640 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
28650 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
28660 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
28670 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
28680 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
28690 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
286a0 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
286b0 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
286c0 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
286d0 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
286e0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
286f0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
28700 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
28710 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
28720 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
28730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28740 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28750 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
28760 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
28770 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
28780 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
28790 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
287a0 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
287b0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
287c0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
287d0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
287e0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
287f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
28800 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
28810 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
28820 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
28830 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
28840 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
28850 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
28860 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
28870 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
28880 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28890 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
288a0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
288b0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
288c0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
288d0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
288e0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
288f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
28900 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
28910 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
28920 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
28930 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
28940 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
28950 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
28960 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
28970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
28980 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
28990 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
289a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
289b0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
289c0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
289d0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
289e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
289f0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
28a00 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
28a10 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
28a20 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
28a30 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
28a40 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
28a50 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
28a60 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
28a70 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
28a80 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
28a90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
28aa0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
28ab0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
28ac0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
28ad0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
28ae0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
28af0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
28b00 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
28b10 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
28b20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
28b30 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
28b40 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
28b50 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
28b60 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
28b70 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
28b80 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
28b90 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
28ba0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28bb0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
28bc0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28bd0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
28be0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
28bf0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
28c00 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
28c10 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
28c20 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
28c30 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
28c40 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
28c50 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
28c60 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
28c70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28c80 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
28c90 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
28ca0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
28cb0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
28cc0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
28cd0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
28ce0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
28cf0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
28d00 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
28d10 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
28d20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28d30 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
28d40 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
28d50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
28d60 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
28d70 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
28d80 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
28d90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
28da0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
28db0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28dc0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
28dd0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
28de0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
28df0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
28e00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
28e10 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
28e20 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
28e30 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
28e40 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
28e50 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
28e60 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
28e70 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  a.**.** The foll
28e80 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
28e90 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
28ea0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
28eb0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
28ec0 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
28ed0 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
28ee0 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
28ef0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
28f00 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
28f10 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
28f20 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
28f30 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
28f40 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
28f50 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
28f60 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
28f70 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
28f80 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
28f90 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
28fa0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
28fb0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
28fc0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
28fd0 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
28fe0 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
28ff0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
29000 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
29010 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
29020 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
29030 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
29040 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
29050 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
29060 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
29070 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
29080 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
29090 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
290a0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
290b0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
290c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
290d0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
290e0 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
290f0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
29100 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
29110 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
29120 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
29130 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
29140 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
29150 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
29160 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29170 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
29180 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
29190 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
291a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
291b0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
291c0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
291d0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
291e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
291f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
29200 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61   ^If no metadata
29210 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
29220 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
29230 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
29240 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
29250 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
29260 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
29270 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
29280 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
29290 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
292a0 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
292b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
292c0 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
292d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
292e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
292f0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _set_auxdata() i
29300 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74  nterface saves t
29310 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70  he metadata.** p
29320 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73  ointed to by its
29330 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61   3rd parameter a
29340 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66  s the metadata f
29350 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
29360 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
29370 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29380 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75  ed function.  Su
29390 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
293a0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74  s to sqlite3_get
293b0 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74  _auxdata() might
293c0 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74   return this dat
293d0 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20  a, if it has.** 
293e0 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79  not been destroy
293f0 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73  ed..** ^If it is
29400 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
29410 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68  e will invoke th
29420 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
29430 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62  function given b
29440 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  y the 4th parame
29450 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  ter to sqlite3_s
29460 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a  et_auxdata() on.
29470 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  ** the metadata 
29480 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
29490 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
294a0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
294b0 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65  s.** or when the
294c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63   SQL statement c
294d0 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65  ompletes, whiche
294e0 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
294f0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73  .**.** SQLite is
29500 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68   free to call th
29510 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64  e destructor and
29520 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f   drop metadata o
29530 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74  n any.** paramet
29540 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69  er of any functi
29550 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20  on at any time. 
29560 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61   ^The only guara
29570 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20  ntee is that.** 
29580 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  the destructor w
29590 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65  ill be called be
295a0 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74  fore the metadat
295b0 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a  a is dropped..**
295c0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
295d0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
295e0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
295f0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
29600 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  for.** expressio
29610 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73  ns that are cons
29620 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20  tant at compile 
29630 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75  time. This inclu
29640 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  des literal.** v
29650 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
29660 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  eters].)^.**.** 
29670 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
29680 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
29690 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
296a0 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
296b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
296c0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
296d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74  oid *sqlite3_get
296e0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
296f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
29700 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29710 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
29720 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29730 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
29740 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
29750 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29760 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
29770 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
29780 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
29790 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
297a0 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
297b0 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
297c0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
297d0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
297e0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
297f0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
29800 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
29810 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
29820 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
29830 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
29840 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
29850 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
29860 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
29870 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
29880 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
29890 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
298a0 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
298b0 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
298c0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
298d0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
298e0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
298f0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
29900 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
29910 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
29920 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
29930 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
29940 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
29950 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
29960 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
29970 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
29980 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
29990 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
299a0 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
299b0 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65   compilers.  See
299c0 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a   ticket #2191..*
299d0 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  /.typedef void (
299e0 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  *sqlite3_destruc
299f0 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29  tor_type)(void*)
29a00 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ;.#define SQLITE
29a10 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73  _STATIC      ((s
29a20 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
29a30 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e  r_type)0).#defin
29a40 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  e SQLITE_TRANSIE
29a50 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64  NT   ((sqlite3_d
29a60 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d  estructor_type)-
29a70 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  1)../*.** CAPI3R
29a80 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20  EF: Setting The 
29a90 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c  Result Of An SQL
29aa0 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20   Function.**.** 
29ab0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
29ac0 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78  re used by the x
29ad0 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63  Func or xFinal c
29ae0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a  allbacks that.**
29af0 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66   implement SQL f
29b00 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
29b10 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a  regates.  See.**
29b20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29b30 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
29b40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29b50 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
29b60 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  * for additional
29b70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
29b80 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
29b90 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75  ons work very mu
29ba0 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72  ch like the [par
29bb0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20  ameter binding] 
29bc0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e  family of.** fun
29bd0 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62  ctions used to b
29be0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f  ind values to ho
29bf0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  st parameters in
29c00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29c10 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74  ents..** Refer t
29c20 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d  o the [SQL param
29c30 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74  eter] documentat
29c40 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
29c50 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
29c60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29c70 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
29c80 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
29c90 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
29ca0 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
29cb0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29cc0 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f  on to be the BLO
29cd0 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20  B whose content 
29ce0 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f  is pointed.** to
29cf0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70   by the second p
29d00 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69  arameter and whi
29d10 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f  ch is N bytes lo
29d20 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  ng where N is th
29d30 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
29d40 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
29d50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29d60 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72  zeroblob() inter
29d70 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65  faces set the re
29d80 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
29d90 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29da0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
29db0 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e  e a BLOB contain
29dc0 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20  ing all zero.** 
29dd0 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65  bytes and N byte
29de0 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65  s in size, where
29df0 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20   N is the value 
29e00 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  of the 2nd param
29e10 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  eter..**.** ^The
29e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29e30 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
29e40 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
29e50 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
29e60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29e70 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
29e80 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
29e90 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
29ea0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
29eb0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
29ec0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
29ed0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
29ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29ef0 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
29f00 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
29f10 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
29f20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
29f30 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
29f40 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
29f50 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
29f60 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
29f70 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
29f80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29f90 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
29fa0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29fb0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
29fc0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
29fd0 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
29fe0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
29ff0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2a000 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2a010 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2a020 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
2a030 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
2a040 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
2a050 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2a060 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
2a070 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
2a080 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
2a090 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2a0a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2a0b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a0c0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2a0d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2a0e0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
2a0f0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2a100 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
2a110 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
2a120 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
2a130 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
2a140 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
2a150 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2a160 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2a170 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
2a180 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a190 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
2a1a0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
2a1b0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
2a1c0 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
2a1d0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2a1e0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
2a1f0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
2a200 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
2a210 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2a220 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
2a230 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2a240 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
2a250 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
2a260 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2a270 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2a280 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
2a290 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
2a2a0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
2a2b0 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
2a2c0 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
2a2d0 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
2a2e0 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
2a2f0 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
2a300 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2a310 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
2a320 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
2a330 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
2a340 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
2a350 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
2a360 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
2a370 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
2a380 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
2a390 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
2a3a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
2a3b0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
2a3c0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
2a3d0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2a3e0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2a3f0 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
2a400 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2a410 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
2a420 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2a430 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62  ite3_result_toob
2a440 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
2a450 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2a460 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
2a470 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
2a480 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
2a490 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
2a4a0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
2a4b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a4c0 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69  result_nomem() i
2a4d0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2a4e0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
2a4f0 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
2a500 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
2a510 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2a520 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
2a530 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a540 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
2a550 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2a560 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2a570 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2a580 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2a590 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
2a5a0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2a5b0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
2a5c0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
2a5d0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
2a5e0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2a5f0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2a600 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2a610 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2a620 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a630 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2a640 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
2a650 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2a660 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2a670 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
2a680 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a690 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
2a6a0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2a6b0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
2a6c0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2a6d0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2a6e0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
2a6f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a700 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2a710 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
2a720 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
2a730 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2a740 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
2a750 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a760 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
2a770 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
2a780 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2a790 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2a7a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2a7b0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
2a7c0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
2a7d0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
2a7e0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
2a7f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
2a800 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
2a810 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
2a820 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
2a830 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
2a840 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
2a850 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
2a860 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
2a870 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
2a880 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
2a890 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a8a0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2a8b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
2a8c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2a8d0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2a8e0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2a8f0 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
2a900 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
2a910 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
2a920 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
2a930 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
2a940 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
2a950 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
2a960 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
2a970 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2a980 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a990 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2a9a0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2a9b0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
2a9c0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
2a9d0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
2a9e0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
2a9f0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2aa00 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
2aa10 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
2aa20 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
2aa30 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a  ction result..**
2aa40 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
2aa50 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2aa60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2aa70 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2aa80 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2aa90 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
2aaa0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
2aab0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
2aac0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
2aad0 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
2aae0 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
2aaf0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
2ab00 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
2ab10 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2ab20 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2ab30 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2ab40 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2ab50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2ab60 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
2ab70 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
2ab80 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
2ab90 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
2aba0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
2abb0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
2abc0 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
2abd0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
2abe0 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
2abf0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2ac00 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
2ac10 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
2ac20 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
2ac30 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
2ac40 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
2ac50 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
2ac60 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2ac70 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2ac80 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2ac90 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2aca0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2acb0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2acc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2acd0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
2ace0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
2acf0 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
2ad00 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
2ad10 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
2ad20 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
2ad30 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
2ad40 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
2ad50 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
2ad60 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
2ad70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ad80 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
2ad90 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2ada0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
2adb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2adc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2add0 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
2ade0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2adf0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2ae00 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
2ae10 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2ae20 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
2ae30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2ae40 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
2ae50 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
2ae60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2ae70 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
2ae80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2ae90 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
2aea0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
2aeb0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
2aec0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
2aed0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
2aee0 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
2aef0 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
2af00 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
2af10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2af20 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
2af30 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
2af40 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
2af50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2af60 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
2af70 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
2af80 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
2af90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2afa0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
2afb0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
2afc0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
2afd0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2afe0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
2aff0 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
2b000 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
2b010 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
2b020 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
2b030 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2b040 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
2b050 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
2b060 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
2b070 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
2b080 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2b090 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2b0a0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
2b0b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2b0c0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2b0d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b0e0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2b0f0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69  sult_double(sqli
2b100 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f  te3_context*, do
2b110 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69  uble);.void sqli
2b120 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b130 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b140 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2b150 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2b160 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2b170 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
2b180 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2b190 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2b1a0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2b1b0 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f  _toobig(sqlite3_
2b1c0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
2b1d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2b1e0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74  rror_nomem(sqlit
2b1f0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2b200 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2b210 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
2b220 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2b230 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2b240 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c  3_result_int(sql
2b250 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2b260 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2b270 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73  3_result_int64(s
2b280 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b290 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2b2a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2b2b0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
2b2c0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2b2d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b2e0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
2b2f0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2b300 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
2b310 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2b320 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b330 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ext16(sqlite3_co
2b340 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2b350 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2b360 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2b370 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2b380 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2b390 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2b3a0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2b3b0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2b3c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b3d0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2b3e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2b3f0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2b400 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2b410 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2b420 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63  _value(sqlite3_c
2b430 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
2b440 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73  _value*);.void s
2b450 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
2b460 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
2b470 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
2b480 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b490 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
2b4a0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
2b4b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
2b4c0 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20  ctions are used 
2b4d0 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61  to add new colla
2b4e0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74  tion sequences t
2b4f0 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  o the.** [databa
2b500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
2b510 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
2b520 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
2b530 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
2b540 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
2b550 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
2b560 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
2b570 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2b580 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2b590 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
2b5a0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
2b5b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2b5c0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
2b5d0 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
2b5e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b5f0 74 69 6f 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c  tion16(). ^In al
2b600 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e  l cases.** the n
2b610 61 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ame is passed as
2b620 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2b630 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2b640 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2b650 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
2b660 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
2b670 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46  ants [SQLITE_UTF
2b680 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  8],.** [SQLITE_U
2b690 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16LE], or [SQL
2b6a0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
2b6b0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
2b6c0 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
2b6d0 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
2b6e0 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
2b6f0 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
2b700 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
2b710 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
2b720 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
2b730 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  , or UTF-16 big-
2b740 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
2b750 76 65 6c 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68  vely. ^The.** th
2b760 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67  ird argument mig
2b770 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49  ht also be [SQLI
2b780 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64  TE_UTF16] to ind
2b790 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72  icate that the r
2b7a0 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74  outine.** expect
2b7b0 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65  s pointers to be
2b7c0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
2b7d0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
2b7e0 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65  te order, or the
2b7f0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e  .** argument can
2b800 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
2b810 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68  6_ALIGNED] if th
2b820 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  e.** the routine
2b830 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
2b840 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64  s to 16-bit word
2b850 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73   aligned strings
2b860 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e  .** of UTF-16 in
2b870 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
2b880 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20   order..**.** A 
2b890 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
2b8a0 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
2b8b0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
2b8c0 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
2b8d0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
2b8e0 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
2b8f0 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20  his is the same 
2b900 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  as deleting the 
2b910 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
2b920 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53  uence (so that S
2b930 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c  QLite cannot cal
2b940 6c 20 69 74 20 61 6e 79 20 6d 6f 72 65 29 2e 0a  l it any more)..
2b950 2a 2a 20 5e 45 61 63 68 20 74 69 6d 65 20 74 68  ** ^Each time th
2b960 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75  e application su
2b970 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20  pplied function 
2b980 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69  is invoked, it i
2b990 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69  s passed.** as i
2b9a0 74 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ts first paramet
2b9b0 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  er a copy of the
2b9c0 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73   void* passed as
2b9d0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
2b9e0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2b9f0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ba00 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
2ba10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2ba20 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  n16()..**.** ^Th
2ba30 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75  e remaining argu
2ba40 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70  ments to the app
2ba50 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
2ba60 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77  d routine are tw
2ba70 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61  o strings,.** ea
2ba80 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  ch represented b
2ba90 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74  y a (length, dat
2baa0 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f  a) pair and enco
2bab0 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ded in the encod
2bac0 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ing.** that was 
2bad0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
2bae0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65  ird argument whe
2baf0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
2bb00 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20  sequence was.** 
2bb10 72 65 67 69 73 74 65 72 65 64 2e 20 20 54 68 65  registered.  The
2bb20 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2bb30 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72  ined collation r
2bb40 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a  outine should.**
2bb50 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65   return negative
2bb60 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69  , zero or positi
2bb70 76 65 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ve if the first 
2bb80 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
2bb90 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f  han,.** equal to
2bba0 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  , or greater tha
2bbb0 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72  n the second str
2bbc0 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e  ing. i.e. (STRIN
2bbd0 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a  G1 - STRING2)..*
2bbe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bbf0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2bc00 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
2bc10 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2bc20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
2bc30 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
2bc40 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61  takes an extra a
2bc50 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
2bc60 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
2bc70 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  r.** the collati
2bc80 6f 6e 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  on.  ^The destru
2bc90 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
2bca0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
2bcb0 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
2bcc0 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
2bcd0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
2bce0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
2bcf0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
2bd00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
2bd10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2bd20 76 32 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  v2()..** ^Collat
2bd30 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79  ions are destroy
2bd40 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
2bd50 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
2bd60 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68  ater calls to th
2bd70 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63  e.** collation c
2bd80 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
2bd90 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64  s or when the [d
2bda0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bdb0 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a  on] is closed.**
2bdc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bdd0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
2bde0 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
2bdf0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2be00 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
2be10 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2be20 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
2be30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2be40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
2be50 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
2be60 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
2be70 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2be80 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2be90 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2bea0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2beb0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2bec0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2bed0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2bee0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
2bef0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
2bf00 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
2bf10 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
2bf20 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
2bf30 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2bf40 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2bf50 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
2bf60 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
2bf70 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
2bf80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2bf90 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2bfa0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
2bfb0 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
2bfc0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2bfd0 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2bfe0 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2bff0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2c000 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2c010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c020 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
2c030 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
2c040 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
2c050 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
2c060 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
2c070 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
2c080 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
2c090 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
2c0a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2c0b0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
2c0c0 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
2c0d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c0e0 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
2c0f0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
2c100 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2c110 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2c120 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
2c130 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
2c140 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
2c150 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
2c160 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2c170 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
2c180 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
2c190 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
2c1a0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2c1b0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
2c1c0 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
2c1d0 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
2c1e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2c1f0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
2c200 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
2c210 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
2c220 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
2c230 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
2c240 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
2c250 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
2c260 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
2c270 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
2c280 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
2c290 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
2c2a0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
2c2b0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2c2c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
2c2d0 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
2c2e0 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
2c2f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2c300 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2c310 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
2c320 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2c330 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
2c340 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2c350 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
2c360 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
2c370 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2c380 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2c390 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2c3a0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
2c3b0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
2c3c0 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
2c3d0 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
2c3e0 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
2c3f0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2c400 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
2c410 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
2c420 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2c430 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2c440 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
2c450 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2c460 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
2c470 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2c480 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
2c490 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2c4a0 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
2c4b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c4c0 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
2c4d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2c4e0 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
2c4f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2c500 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2c510 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2c520 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2c530 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
2c540 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
2c550 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2c560 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2c570 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
2c580 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2c590 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2c5a0 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2c5b0 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
2c5c0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2c5d0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2c5e0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2c5f0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
2c600 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
2c610 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
2c620 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
2c630 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
2c640 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
2c650 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
2c660 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
2c670 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
2c680 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
2c690 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
2c6a0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
2c6b0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
2c6c0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
2c6d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c6e0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2c6f0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2c700 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2c710 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2c720 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2c730 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2c740 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
2c750 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
2c760 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
2c770 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
2c780 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
2c790 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
2c7a0 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
2c7b0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
2c7c0 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
2c7d0 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
2c7e0 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
2c7f0 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
2c800 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2c810 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2c820 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2c830 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2c840 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2c850 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2c860 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
2c870 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2c880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c890 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2c8a0 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2c8b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2c8c0 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2c8d0 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
2c8e0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
2c8f0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2c900 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
2c910 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
2c920 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
2c930 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
2c940 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
2c950 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
2c960 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2c970 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
2c980 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2c990 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2c9a0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2c9b0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
2c9c0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
2c9d0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
2c9e0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2c9f0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
2ca00 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2ca10 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2ca20 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
2ca30 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
2ca40 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
2ca50 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
2ca60 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
2ca70 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2ca80 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2ca90 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2caa0 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
2cab0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
2cac0 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
2cad0 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
2cae0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2caf0 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69  3_sleep() functi
2cb00 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75  on causes the cu
2cb10 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20  rrent thread to 
2cb20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f  suspend executio
2cb30 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73  n.** for at leas
2cb40 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  t a number of mi
2cb50 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69  lliseconds speci
2cb60 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61  fied in its para
2cb70 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  meter..**.** ^If
2cb80 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2cb90 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
2cba0 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
2cbb0 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
2cbc0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
2cbd0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
2cbe0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
2cbf0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
2cc00 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
2cc10 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65  cond. ^The numbe
2cc20 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2cc30 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
2cc40 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
2cc50 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
2cc60 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
2cc70 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
2cc80 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
2cc90 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2cca0 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
2ccb0 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
2ccc0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
2ccd0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
2cce0 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  bject..*/.int sq
2ccf0 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
2cd00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cd10 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
2cd20 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
2cd30 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a  mporary Files.**
2cd40 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
2cd50 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
2cd60 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2cd70 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
2cd80 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
2cd90 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
2cda0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
2cdb0 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
2cdc0 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
2cdd0 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68  ted by SQLite wh
2cde0 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
2cdf0 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  -in [sqlite3_vfs
2ce00 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20   | VFS].** will 
2ce10 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
2ce20 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20  t directory.)^  
2ce30 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
2ce40 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
2ce50 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2ce60 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
2ce70 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
2ce80 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
2ce90 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
2cea0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
2ceb0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2cec0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2ced0 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
2cee0 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
2cef0 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
2cf00 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
2cf10 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
2cf20 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
2cf30 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
2cf40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2cf50 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
2cf60 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
2cf70 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
2cf80 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
2cf90 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
2cfa0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
2cfb0 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
2cfc0 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
2cfd0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
2cfe0 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
2cff0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
2d000 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
2d010 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
2d020 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
2d030 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2d040 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
2d050 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d  .**.** ^The [tem
2d060 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
2d070 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
2d080 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
2d090 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
2d0a0 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
2d0b0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2d0c0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2d0d0 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d  loc].  ^Furtherm
2d0e0 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d  ore,.** the [tem
2d0f0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
2d100 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73  y pragma] always
2d110 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e   assumes that an
2d120 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74  y string.** that
2d130 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70   this variable p
2d140 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64  oints to is held
2d150 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2d160 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
2d170 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e  lite3_malloc] an
2d180 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79  d the pragma may
2d190 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   attempt to free
2d1a0 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   that memory.** 
2d1b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2d1c0 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  ree]..** Hence, 
2d1d0 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  if this variable
2d1e0 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72   is modified dir
2d1f0 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74  ectly, either it
2d200 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61   should be.** ma
2d210 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20  de NULL or made 
2d220 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
2d230 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
2d240 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2d250 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65  ].** or else the
2d260 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d   use of the [tem
2d270 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
2d280 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64  y pragma] should
2d290 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a   be avoided..*/.
2d2a0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
2d2b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70  ar *sqlite3_temp
2d2c0 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
2d2d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
2d2e0 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69  t For Auto-Commi
2d2f0 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52  t Mode.** KEYWOR
2d300 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20  DS: {autocommit 
2d310 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mode}.**.** ^The
2d320 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
2d330 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66  ocommit() interf
2d340 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
2d350 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20  zero or.** zero 
2d360 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74  if the given dat
2d370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d380 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
2d390 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   autocommit mode
2d3a0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
2d3b0 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  y.  ^Autocommit 
2d3c0 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
2d3d0 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  fault..** ^Autoc
2d3e0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
2d3f0 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
2d400 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
2d410 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
2d420 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64  de is re-enabled
2d430 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
2d440 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
2d450 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
2d460 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
2d470 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
2d480 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
2d490 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
2d4a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72  transaction (err
2d4b0 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53  ors including [S
2d4c0 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51  QLITE_FULL], [SQ
2d4d0 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20  LITE_IOERR],.** 
2d4e0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20  [SQLITE_NOMEM], 
2d4f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61  [SQLITE_BUSY], a
2d500 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  nd [SQLITE_INTER
2d510 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a  RUPT]) then the.
2d520 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  ** transaction m
2d530 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62  ight be rolled b
2d540 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
2d550 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79  y.  The only way
2d560 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20   to.** find out 
2d570 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61  whether SQLite a
2d580 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
2d590 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
2d5a0 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
2d5b0 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
2d5c0 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
2d5d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  on..**.** If ano
2d5e0 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e  ther thread chan
2d5f0 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d  ges the autocomm
2d600 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65  it status of the
2d610 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2d620 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
2d630 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
2d640 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
2d650 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2d660 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
2d670 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
2d680 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
2d690 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
2d6a0 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65  PI3REF: Find The
2d6b0 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
2d6c0 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
2d6d0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2d6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
2d6f0 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
2d700 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
2d710 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d720 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
2d730 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
2d740 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
2d750 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61  ngs.  ^The [data
2d760 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d770 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2d780 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2d790 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64  e is the same [d
2d7a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d7b0 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  on].** that was 
2d7c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2d7d0 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
2d7e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d7f0 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
2d800 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
2d810 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
2d820 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
2d830 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
2d840 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74   place..*/.sqlit
2d850 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68  e3 *sqlite3_db_h
2d860 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  andle(sqlite3_st
2d870 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2d880 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20  I3REF: Find the 
2d890 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74  next prepared st
2d8a0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
2d8b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
2d8c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2d8d0 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65  to the next [pre
2d8e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d8f0 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20   after.** pStmt 
2d900 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2d910 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2d920 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20  nnection] pDb.  
2d930 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c  ^If pStmt is NUL
2d940 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69  L.** then this i
2d950 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d960 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2d970 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64  e first prepared
2d980 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73   statement.** as
2d990 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2d9a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d9b0 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20  ction pDb.  ^If 
2d9c0 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
2d9d0 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
2d9e0 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
2d9f0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
2da00 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
2da10 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64  LL..**.** The [d
2da20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2da30 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
2da40 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2da50 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
2da60 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65  (D,S)] must refe
2da70 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74  r to an open dat
2da80 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2da90 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
2daa0 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
2dab0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
2dac0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d  ..*/.sqlite3_stm
2dad0 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
2dae0 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
2daf0 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
2db00 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2db10 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
2db20 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
2db30 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
2db40 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
2db50 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2db60 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2db70 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2db80 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2db90 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2dba0 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2dbb0 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
2dbc0 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
2dbd0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2dbe0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2dbf0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2dc00 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
2dc10 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2dc20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2dc30 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2dc40 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  n..** ^The sqlit
2dc50 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2dc60 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2dc70 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2dc80 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
2dc90 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2dca0 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
2dcb0 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20  on is [ROLLBACK 
2dcc0 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a  | rolled back]..
2dcd0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
2dce0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2dcf0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
2dd00 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2dd10 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2dd20 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2dd30 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2dd40 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41  dden..** ^The pA
2dd50 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
2dd60 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
2dd70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2dd80 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
2dd90 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
2dda0 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
2ddb0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
2ddc0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
2ddd0 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
2dde0 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
2ddf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2de00 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
2de10 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65  ,C,P) and sqlite
2de20 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2de30 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73  D,C,P) functions
2de40 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50  .** return the P
2de50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
2de60 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2de70 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2de80 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20  ction.** on the 
2de90 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2dea0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
2deb0 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
2dec0 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20   first call for 
2ded0 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e  each function on
2dee0 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61   D..**.** The ca
2def0 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74  llback implement
2df00 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
2df10 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
2df20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
2df30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2df40 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
2df50 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ked the callback
2df60 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
2df70 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
2df80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2df90 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
2dfa0 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
2dfb0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
2dfc0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
2dfd0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2dfe0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
2dff0 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20  he commit.** or 
2e000 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e  rollback hook in
2e010 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2e020 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
2e030 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2e040 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2e050 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
2e060 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
2e070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e080 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
2e090 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
2e0a0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
2e0b0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73  ph..**.** ^Regis
2e0c0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
2e0d0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2e0e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2e0f0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f  .** ^When the co
2e100 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
2e110 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ck routine retur
2e120 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f  ns zero, the [CO
2e130 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69  MMIT].** operati
2e140 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  on is allowed to
2e150 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c   continue normal
2e160 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d  ly.  ^If the com
2e170 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75  mit hook.** retu
2e180 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
2e190 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20  en the [COMMIT] 
2e1a0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
2e1b0 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a  o a [ROLLBACK]..
2e1c0 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
2e1d0 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64   hook is invoked
2e1e0 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74   on a rollback t
2e1f0 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  hat results from
2e200 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f   a commit.** hoo
2e210 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d  k returning non-
2e220 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74  zero, just as it
2e230 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61   would be with a
2e240 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63  ny other rollbac
2e250 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  k..**.** ^For th
2e260 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
2e270 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
2e280 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
2e290 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f   have been.** ro
2e2a0 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
2e2b0 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
2e2c0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
2e2d0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
2e2e0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
2e2f0 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
2e300 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
2e310 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
2e320 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63   ^The rollback c
2e330 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2e340 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2e350 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
2e360 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2e370 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
2e380 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e390 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
2e3a0 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
2e3b0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75  o the [sqlite3_u
2e3c0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e  pdate_hook()] in
2e3d0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64  terface..*/.void
2e3e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   *sqlite3_commit
2e3f0 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20  _hook(sqlite3*, 
2e400 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
2e410 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
2e420 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2e430 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ok(sqlite3*, voi
2e440 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f  d(*)(void *), vo
2e450 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
2e460 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e  I3REF: Data Chan
2e470 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ge Notification 
2e480 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
2e490 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
2e4a0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
2e4b0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2e4c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2e4d0 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
2e4e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e4f0 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
2e500 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
2e510 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
2e520 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2e530 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
2e540 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
2e550 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63  leted..** ^Any c
2e560 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
2e570 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2e580 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  o this function.
2e590 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2e5a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e5b0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2e5c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  n..**.** ^The se
2e5d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2e5e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2e5f0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
2e600 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
2e610 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
2e620 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
2e630 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ed..** ^The firs
2e640 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2e650 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
2e660 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
2e670 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
2e680 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2e690 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20  hook()..** ^The 
2e6a0 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20  second callback 
2e6b0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
2e6c0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
2e6d0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
2e6e0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  TE],.** or [SQLI
2e6f0 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65  TE_UPDATE], depe
2e700 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65  nding on the ope
2e710 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73  ration that caus
2e720 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  ed the callback.
2e730 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2e740 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  ..** ^The third 
2e750 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
2e760 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
2e770 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
2e780 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
2e790 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
2e7a0 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
2e7b0 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
2e7c0 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e  row..** ^The fin
2e7d0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61  al callback para
2e7e0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f  meter is the [ro
2e7f0 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e  wid] of the row.
2e800 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65  .** ^In the case
2e810 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74   of an update, t
2e820 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69  his is the [rowi
2e830 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64  d] after the upd
2e840 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e  ate takes place.
2e850 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64  .**.** ^(The upd
2e860 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20  ate hook is not 
2e870 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74  invoked when int
2e880 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62  ernal system tab
2e890 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66  les are.** modif
2e8a0 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65  ied (i.e. sqlite
2e8b0 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69  _master and sqli
2e8c0 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a  te_sequence).)^.
2e8d0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75  **.** ^In the cu
2e8e0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
2e8f0 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65  tion, the update
2e900 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20   hook.** is not 
2e910 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70  invoked when dup
2e920 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72  lication rows ar
2e930 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73  e deleted becaus
2e940 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43  e of an.** [ON C
2e950 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e  ONFLICT | ON CON
2e960 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63  FLICT REPLACE] c
2e970 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20  lause.  ^Nor is 
2e980 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2e990 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ** invoked when 
2e9a0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
2e9b0 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e   using the [trun
2e9c0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
2e9d0 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70  n]..** The excep
2e9e0 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e  tions defined in
2e9f0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20   this paragraph 
2ea00 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
2ea10 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
2ea20 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
2ea30 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20  *.** The update 
2ea40 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  hook implementat
2ea50 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
2ea60 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
2ea70 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
2ea80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ea90 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
2eaa0 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  d the update hoo
2eab0 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a  k.  Any actions.
2eac0 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65  ** to modify the
2ead0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2eae0 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66  tion must be def
2eaf0 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65  erred until afte
2eb00 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  r the.** complet
2eb10 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
2eb20 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c  te3_step()] call
2eb30 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
2eb40 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e  the update hook.
2eb50 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
2eb60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2eb70 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2eb80 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
2eb90 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
2eba0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ebb0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
2ebc0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
2ebd0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
2ebe0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  h..**.** ^The sq
2ebf0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2ec00 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f  k(D,C,P) functio
2ec10 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  n.** returns the
2ec20 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d   P argument from
2ec30 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2ec40 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d  ll.** on the sam
2ec50 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2ec60 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55  ection] D, or NU
2ec70 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69  LL for.** the fi
2ec80 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a  rst call on D..*
2ec90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
2eca0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
2ecb0 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73  t_hook()] and [s
2ecc0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2ecd0 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  hook()].** inter
2ece0 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  faces..*/.void *
2ecf0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2ed00 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ook(.  sqlite3*,
2ed10 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
2ed20 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e   *,int ,char con
2ed30 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20  st *,char const 
2ed40 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
2ed50 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a  ,.  void*.);../*
2ed60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
2ed70 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
2ed80 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63  Shared Pager Cac
2ed90 68 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  he.** KEYWORDS: 
2eda0 7b 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a  {shared cache}.*
2edb0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2edc0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
2edd0 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72  isables the shar
2ede0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
2edf0 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64  ase cache.** and
2ee00 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72   schema data str
2ee10 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20  uctures between 
2ee20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2ee30 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f  tion | connectio
2ee40 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61  ns].** to the sa
2ee50 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61  me database. Sha
2ee60 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2ee70 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
2ee80 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64  is true.** and d
2ee90 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  isabled if the a
2eea0 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65  rgument is false
2eeb0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65  .)^.**.** ^Cache
2eec0 20 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   sharing is enab
2eed0 6c 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64  led and disabled
2eee0 20 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70   for an entire p
2eef0 72 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20  rocess..** This 
2ef00 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
2ef10 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
2ef20 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72   3.5.0. In prior
2ef30 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2ef40 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20  ite,.** sharing 
2ef50 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
2ef60 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
2ef70 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
2ef80 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ly..**.** ^(The 
2ef90 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
2efa0 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
2efb0 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
2efc0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
2efd0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
2efe0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2eff0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2f000 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2f010 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
2f020 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
2f030 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
2f040 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
2f050 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
2f060 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
2f070 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
2f080 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a   were opened.)^.
2f090 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
2f0a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
2f0b0 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72  LITE_OK] if shar
2f0c0 65 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61  ed cache was ena
2f0d0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2f0e0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2f0f0 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64  .  An [error cod
2f100 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f  e] is returned o
2f110 74 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a  therwise.)^.**.*
2f120 2a 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20  * ^Shared cache 
2f130 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
2f140 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73  efault. But this
2f150 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
2f160 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61  .** future relea
2f170 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ses of SQLite.  
2f180 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
2f190 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61  t care about sha
2f1a0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74  red.** cache set
2f1b0 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20  ting should set 
2f1c0 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a  it explicitly..*
2f1d0 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20  *.** See Also:  
2f1e0 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43  [SQLite Shared-C
2f1f0 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e  ache Mode].*/.in
2f200 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
2f210 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
2f220 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f230 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20  REF: Attempt To 
2f240 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
2f250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f260 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2f270 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
2f280 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
2f290 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65  N bytes.** of he
2f2a0 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
2f2b0 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
2f2c0 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61  sential memory a
2f2d0 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65  llocations.** he
2f2e0 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
2f2f0 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20 4d 65  se library.   Me
2f300 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63  mory used to cac
2f310 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
2f320 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
2f330 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61  performance is a
2f340 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e  n example of non
2f350 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
2f360 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  y..** ^sqlite3_r
2f370 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
2f380 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2f390 65 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75  er of bytes actu
2f3a0 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77  ally freed,.** w
2f3b0 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f  hich might be mo
2f3c0 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20  re or less than 
2f3d0 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65  the amount reque
2f3e0 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sted..** ^The sq
2f3f0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2f400 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65 20 69  mory() routine i
2f410 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75 72 6e  s a no-op return
2f420 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66 20 53  ing zero.** if S
2f430 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63 6f 6d  QLite is not com
2f440 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
2f450 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
2f460 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2f  _MANAGEMENT]..*/
2f470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
2f480 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
2f490 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f4a0 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
2f4b0 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
2f4c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f4d0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
2f4e0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c  t() interface pl
2f4f0 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69  aces a "soft" li
2f500 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d  mit.** on the am
2f510 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
2f520 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
2f530 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
2f540 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 69  ite..** ^If an i
2f550 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69  nternal allocati
2f560 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 20  on is requested 
2f570 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65 65  that would excee
2f580 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65  d the.** soft he
2f590 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74  ap limit, [sqlit
2f5a0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2f5b0 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20  y()] is invoked 
2f5c0 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  one or.** more t
2f5d0 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70 20  imes to free up 
2f5e0 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f 72  some space befor
2f5f0 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  e the allocation
2f600 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   is performed..*
2f610 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74 20  *.** ^The limit 
2f620 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74 22  is called "soft"
2f630 20 62 65 63 61 75 73 65 20 69 66 20 5b 73 71 6c   because if [sql
2f640 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2f650 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74  ory()].** cannot
2f660 20 66 72 65 65 20 73 75 66 66 69 63 69 65 6e 74   free sufficient
2f670 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65 76 65   memory to preve
2f680 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66 72 6f  nt the limit fro
2f690 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64 65 64  m being exceeded
2f6a0 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  ,.** the memory 
2f6b0 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79  is allocated any
2f6c0 77 61 79 20 61 6e 64 20 74 68 65 20 63 75 72 72  way and the curr
2f6d0 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  ent operation pr
2f6e0 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  oceeds..**.** ^A
2f6f0 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65 72   negative or zer
2f700 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65  o value for N me
2f710 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20 69  ans that there i
2f720 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20 6c  s no soft heap l
2f730 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  imit and.** [sql
2f740 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2f750 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79  ory()] will only
2f760 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2f770 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75 73  memory is exhaus
2f780 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ted..** ^The def
2f790 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
2f7a0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
2f7b0 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
2f7c0 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b 65 73  * ^(SQLite makes
2f7d0 20 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74   a best effort t
2f7e0 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74  o honor the soft
2f7f0 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20   heap limit..** 
2f800 42 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20  But if the soft 
2f810 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f  heap limit canno
2f820 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78  t be honored, ex
2f830 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20  ecution will.** 
2f840 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74  continue without
2f850 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69   error or notifi
2f860 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20  cation.)^  This 
2f870 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d 69 74  is why the limit
2f880 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20   is.** called a 
2f890 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20 20 49  "soft" limit.  I
2f8a0 74 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e  t is advisory on
2f8b0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ly..**.** Prior 
2f8c0 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
2f8d0 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f  n 3.5.0, this ro
2f8e0 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74  utine only const
2f8f0 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72  rained the memor
2f900 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62  y.** allocated b
2f910 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
2f920 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74 68 72  d - the same thr
2f930 65 61 64 20 69 6e 20 77 68 69 63 68 20 74 68 69  ead in which thi
2f940 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e  s routine.** run
2f950 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20 77 69  s.  Beginning wi
2f960 74 68 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  th SQLite versio
2f970 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66  n 3.5.0, the sof
2f980 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 0a  t heap limit is.
2f990 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20 61 6c  ** applied to al
2f9a0 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65 20 76  l threads. The v
2f9b0 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 20 66  alue specified f
2f9c0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2f9d0 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20   limit.** is an 
2f9e0 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74  upper bound on t
2f9f0 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20  he total memory 
2fa00 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
2fa10 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a  ll threads. In.*
2fa20 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  * version 3.5.0 
2fa30 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 63 68  there is no mech
2fa40 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69  anism for limiti
2fa50 6e 67 20 74 68 65 20 68 65 61 70 20 75 73 61 67  ng the heap usag
2fa60 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64  e for.** individ
2fa70 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  ual threads..*/.
2fa80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
2fa90 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
2faa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fab0 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61  EF: Extract Meta
2fac0 64 61 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c  data About A Col
2fad0 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a  umn Of A Table.*
2fae0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
2faf0 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64  ne returns metad
2fb00 61 74 61 20 61 62 6f 75 74 20 61 20 73 70 65 63  ata about a spec
2fb10 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61  ific column of a
2fb20 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74   specific.** dat
2fb30 61 62 61 73 65 20 74 61 62 6c 65 20 61 63 63 65  abase table acce
2fb40 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65  ssible using the
2fb50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2fb60 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
2fb70 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2fb80 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72  irst function ar
2fb90 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2fba0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65  he column is ide
2fbb0 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
2fbc0 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64  econd, third and
2fbd0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2fbe0 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75  rs to.** this fu
2fbf0 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63  nction. ^The sec
2fc00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2fc10 20 65 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65   either the name
2fc20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2fc30 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22  .** (i.e. "main"
2fc40 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20  , "temp", or an 
2fc50 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2fc60 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  e) containing th
2fc70 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74  e specified.** t
2fc80 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49  able or NULL. ^I
2fc90 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
2fca0 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20  en all attached 
2fcb0 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73 65  databases are se
2fcc0 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68  arched.** for th
2fcd0 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68  e table using th
2fce0 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
2fcf0 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61 74   used by the dat
2fd00 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a  abase engine to.
2fd10 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61  ** resolve unqua
2fd20 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65 66  lified table ref
2fd30 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  erences..**.** ^
2fd40 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2fd50 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2fd60 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2fd70 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
2fd80 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
2fd90 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
2fda0 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
2fdb0 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
2fdc0 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
2fdd0 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
2fde0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61  L..**.** ^Metada
2fdf0 74 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ta is returned b
2fe00 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  y writing to the
2fe10 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e   memory location
2fe20 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2fe30 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65  5th.** and subse
2fe40 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73  quent parameters
2fe50 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
2fe60 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65  n. ^Any of these
2fe70 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62   arguments may b
2fe80 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68  e.** NULL, in wh
2fe90 69 63 68 20 63 61 73 65 20 74 68 65 20 63 6f 72  ich case the cor
2fea0 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65  responding eleme
2feb0 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69  nt of metadata i
2fec0 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  s omitted..**.**
2fed0 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a   ^(<blockquote>.
2fee0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
2fef0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
2ff00 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e  > Parameter <th>
2ff10 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20   Output<br>Type 
2ff20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f  <th>  Descriptio
2ff30 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2ff40 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   5th <td> const 
2ff50 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20  char* <td> Data 
2ff60 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  type.** <tr><td>
2ff70 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20   6th <td> const 
2ff80 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20  char* <td> Name 
2ff90 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61  of default colla
2ffa0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a  tion sequence.**
2ffb0 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74   <tr><td> 7th <t
2ffc0 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c  d> int         <
2ffd0 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75  td> True if colu
2ffe0 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c  mn has a NOT NUL
2fff0 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  L constraint.** 
30000 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64  <tr><td> 8th <td
30010 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
30020 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
30030 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  n is part of the
30040 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20   PRIMARY KEY.** 
30050 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64  <tr><td> 9th <td
30060 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74  > int         <t
30070 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d  d> True if colum
30080 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d  n is [AUTOINCREM
30090 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  ENT].** </table>
300a0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
300b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  >)^.**.** ^The m
300c0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f  emory pointed to
300d0 20 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65   by the characte
300e0 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  r pointers retur
300f0 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64  ned for the.** d
30100 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20  eclaration type 
30110 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  and collation se
30120 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20  quence is valid 
30130 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e  only until the n
30140 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61  ext.** call to a
30150 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75  ny SQLite API fu
30160 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nction..**.** ^I
30170 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20  f the specified 
30180 74 61 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c  table is actuall
30190 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72  y a view, an [er
301a0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
301b0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  urned..**.** ^If
301c0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 63   the specified c
301d0 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22  olumn is "rowid"
301e0 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77  , "oid" or "_row
301f0 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b  id_" and an.** [
30200 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
30210 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20  KEY] column has 
30220 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20  been explicitly 
30230 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74  declared, then t
30240 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
30250 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
30260 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63 69 74  for the explicit
30270 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
30280 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69  mn. ^(If there i
30290 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74  s no.** explicit
302a0 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54  ly declared [INT
302b0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
302c0 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74  ] column, then t
302d0 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72  he output.** par
302e0 61 6d 65 74 65 72 73 20 61 72 65 20 73 65 74 20  ameters are set 
302f0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
30300 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64  * <pre>.**     d
30310 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47  ata type: "INTEG
30320 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61  ER".**     colla
30330 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22  tion sequence: "
30340 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e  BINARY".**     n
30350 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20  ot null: 0.**   
30360 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31    primary key: 1
30370 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63  .**     auto inc
30380 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70  rement: 0.** </p
30390 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  re>)^.**.** ^(Th
303a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
303b0 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  load one or more
303c0 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61   schemas from da
303d0 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66  tabase files. If
303e0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63   an.** error occ
303f0 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73 20  urs during this 
30400 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74  process, or if t
30410 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61 62  he requested tab
30420 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  le or column.** 
30430 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c  cannot be found,
30440 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
30450 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
30460 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
30470 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65  e left.** in the
30480 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30490 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65  ction] (to be re
304a0 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73 71  trieved using sq
304b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e  lite3_errmsg()).
304c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  )^.**.** ^This A
304d0 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  PI is only avail
304e0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
304f0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
30500 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
30510 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
30520 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
30530 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
30540 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69  ol defined..*/.i
30550 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
30560 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
30570 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
30580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30590 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
305a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
305b0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
305c0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
305d0 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
305e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
305f0 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
30600 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
30610 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
30620 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
30630 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
30640 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
30650 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
30660 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
30670 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
30680 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
30690 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
306a0 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
306b0 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
306c0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
306d0 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
306e0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
306f0 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
30700 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
30710 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
30720 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
30730 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
30740 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
30750 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
30760 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
30770 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
30780 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
30790 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
307a0 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
307b0 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
307c0 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
307d0 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
307e0 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
307f0 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
30800 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
30810 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
30820 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
30830 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
30840 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
30850 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
30860 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
30870 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
30880 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
30890 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
308a0 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
308b0 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
308c0 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
308d0 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
308e0 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
308f0 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
30900 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
30910 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
30920 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
30930 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
30940 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
30950 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
30960 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
30970 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
30980 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
30990 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
309a0 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
309b0 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
309c0 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
309d0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
309e0 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
309f0 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
30a00 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
30a10 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
30a20 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
30a30 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
30a40 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
30a50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
30a60 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
30a70 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
30a80 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
30a90 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
30aa0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
30ab0 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
30ac0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
30ad0 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
30ae0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
30af0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
30b00 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
30b10 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
30b20 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
30b30 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
30b40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
30b50 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
30b60 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
30b70 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
30b80 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  int sqlite3_load
30b90 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71  _extension(.  sq
30ba0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
30bb0 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20      /* Load the 
30bc0 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74  extension into t
30bd0 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e  his database con
30be0 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  nection */.  con
30bf0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
30c00 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
30c10 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72 79  e shared library
30c20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65   containing exte
30c30 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  nsion */.  const
30c40 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20   char *zProc,   
30c50 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e   /* Entry point.
30c60 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a    Derived from z
30c70 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63  File if 0 */.  c
30c80 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20  har **pzErrMsg  
30c90 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f       /* Put erro
30ca0 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20 69  r message here i
30cb0 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f  f not 0 */.);../
30cc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
30cd0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
30ce0 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
30cf0 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20  ng.**.** ^So as 
30d00 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75  not to open secu
30d10 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c  rity holes in ol
30d20 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  der applications
30d30 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70   that are.** unp
30d40 72 65 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20  repared to deal 
30d50 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c  with extension l
30d60 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61  oading, and as a
30d70 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c   means of disabl
30d80 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  ing.** extension
30d90 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65   loading while e
30da0 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65  valuating user-e
30db0 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20  ntered SQL, the 
30dc0 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a  following API.**
30dd0 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
30de0 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  turn the [sqlite
30df0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
30e00 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e  ()] mechanism on
30e10 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20   and off..**.** 
30e20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69  ^Extension loadi
30e30 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66  ng is off by def
30e40 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74  ault. See ticket
30e50 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c   #1863..** ^Call
30e60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61   the sqlite3_ena
30e70 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
30e80 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74  on() routine wit
30e90 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f  h onoff==1.** to
30ea0 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20   turn extension 
30eb0 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63  loading on and c
30ec0 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66  all it with onof
30ed0 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20  f==0 to turn.** 
30ee0 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69  it back off agai
30ef0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
30f00 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
30f10 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20  tension(sqlite3 
30f20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  *db, int onoff);
30f30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30f40 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  : Automatically 
30f50 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f  Load An Extensio
30f60 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41  ns.**.** ^This A
30f70 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65  PI can be invoke
30f80 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61  d at program sta
30f90 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f  rtup in order to
30fa0 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65   register.** one
30fb0 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61   or more statica
30fc0 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e  lly linked exten
30fd0 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20  sions that will 
30fe0 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  be available.** 
30ff0 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61  to all new [data
31000 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
31010 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ]..**.** ^(This 
31020 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61  routine stores a
31030 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
31040 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20  extension entry 
31050 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61  point.** in an a
31060 72 72 61 79 20 74 68 61 74 20 69 73 20 6f 62 74  rray that is obt
31070 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
31080 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
31090 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  That memory.** i
310a0 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  s deallocated by
310b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
310c0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
310d0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ].)^.**.** ^This
310e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
310f0 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  ers an extension
31100 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61   entry point tha
31110 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  t is.** automati
31120 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68  cally invoked wh
31130 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61  enever a new [da
31140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31150 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20  n].** is opened 
31160 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  using [sqlite3_o
31170 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
31180 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f  _open16()],.** o
31190 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
311a0 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69  v2()]..** ^Dupli
311b0 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20  cate extensions 
311c0 61 72 65 20 64 65 74 65 63 74 65 64 20 73 6f 20  are detected so 
311d0 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  calling this rou
311e0 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  tine.** multiple
311f0 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
31200 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69  same extension i
31210 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e  s harmless..** ^
31220 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  Automatic extens
31230 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73  ions apply acros
31240 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  s all threads..*
31250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
31260 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
31270 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  d (*xEntryPoint)
31280 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void));../*.** 
31290 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
312a0 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
312b0 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
312c0 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
312d0 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
312e0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
312f0 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a  ered automatic.*
31300 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74  * extensions. It
31310 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
31320 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a  ct of all prior.
31330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f  ** [sqlite3_auto
31340 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61  _extension()] ca
31350 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lls.)^.**.** ^Th
31360 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
31370 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65  bles automatic e
31380 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c  xtensions in all
31390 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69   threads..*/.voi
313a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f  d sqlite3_reset_
313b0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
313c0 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  oid);../*.** The
313d0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68   interface to th
313e0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
313f0 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72  mechanism is cur
31400 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
31410 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72  d.** to be exper
31420 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e  imental.  The in
31430 74 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68  terface might ch
31440 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74  ange in incompat
31450 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66  ible ways..** If
31460 20 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c   this is a probl
31470 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e  em for you, do n
31480 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72  ot use the inter
31490 66 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d  face at this tim
314a0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
314b0 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20  e virtual-table 
314c0 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c  mechanism stabil
314d0 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65  izes, we will de
314e0 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74  clare the.** int
314f0 65 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75  erface fixed, su
31500 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e  pport it indefin
31510 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76  itely, and remov
31520 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a  e this comment..
31530 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74  */../*.** Struct
31540 75 72 65 73 20 75 73 65 64 20 62 79 20 74 68 65  ures used by the
31550 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   virtual table i
31560 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65  nterface.*/.type
31570 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
31580 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f  e3_vtab sqlite3_
31590 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74  vtab;.typedef st
315a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
315b0 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f  ex_info sqlite3_
315c0 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65  index_info;.type
315d0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
315e0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73  e3_vtab_cursor s
315f0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
31600 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  or;.typedef stru
31610 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  ct sqlite3_modul
31620 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  e sqlite3_module
31630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31640 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
31650 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
31660 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64  RDS: sqlite3_mod
31670 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62  ule {virtual tab
31680 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a  le module}.**.**
31690 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 2c   This structure,
316a0 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65   sometimes calle
316b0 64 20 61 20 61 20 22 76 69 72 74 75 61 6c 20 74  d a a "virtual t
316c0 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a  able module", .*
316d0 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d  * defines the im
316e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
316f0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
31700 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74  s].  .** This st
31710 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73  ructure consists
31720 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f   mostly of metho
31730 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c  ds for the modul
31740 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74  e..**.** ^A virt
31750 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
31760 20 69 73 20 63 72 65 61 74 65 64 20 62 79 20 66   is created by f
31770 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73  illing in a pers
31780 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e  istent.** instan
31790 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
317a0 74 75 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67  ture and passing
317b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
317c0 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74  at instance.** t
317d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
317e0 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b  e_module()] or [
317f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
31800 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  odule_v2()]..** 
31810 5e 54 68 65 20 72 65 67 69 73 74 72 61 74 69 6f  ^The registratio
31820 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20  n remains valid 
31830 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c  until it is repl
31840 61 63 65 64 20 62 79 20 61 20 64 69 66 66 65 72  aced by a differ
31850 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72  ent.** module or
31860 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61   until the [data
31870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31880 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f   closes.  The co
31890 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73  ntent.** of this
318a0 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
318b0 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65  not change while
318c0 20 69 74 20 69 73 20 72 65 67 69 73 74 65 72 65   it is registere
318d0 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61  d with.** any da
318e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
318f0 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  n..*/.struct sql
31900 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20  ite3_module {.  
31910 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
31920 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29 28 73  int (*xCreate)(s
31930 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
31940 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
31950 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
31960 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
31970 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
31980 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
31990 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
319a0 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  **);.  int (*xCo
319b0 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c  nnect)(sqlite3*,
319c0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
319d0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
319e0 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
319f0 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
31a00 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
31a10 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
31a20 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
31a30 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29  nt (*xBestIndex)
31a40 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
31a50 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e  VTab, sqlite3_in
31a60 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e  dex_info*);.  in
31a70 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29  t (*xDisconnect)
31a80 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
31a90 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
31aa0 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33  Destroy)(sqlite3
31ab0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
31ac0 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
31ad0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
31ae0 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  b, sqlite3_vtab_
31af0 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f  cursor **ppCurso
31b00 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  r);.  int (*xClo
31b10 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  se)(sqlite3_vtab
31b20 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
31b30 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69   (*xFilter)(sqli
31b40 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
31b50 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f  , int idxNum, co
31b60 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53 74 72  nst char *idxStr
31b70 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
31b80 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69    int argc, sqli
31b90 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76  te3_value **argv
31ba0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74  );.  int (*xNext
31bb0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
31bc0 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
31bd0 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76  *xEof)(sqlite3_v
31be0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
31bf0 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73  int (*xColumn)(s
31c00 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
31c10 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  or*, sqlite3_con
31c20 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  text*, int);.  i
31c30 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c  nt (*xRowid)(sql
31c40 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
31c50 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
31c60 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74   *pRowid);.  int
31c70 20 28 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69   (*xUpdate)(sqli
31c80 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c  te3_vtab *, int,
31c90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
31ca0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
31cb0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65   *);.  int (*xBe
31cc0 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  gin)(sqlite3_vta
31cd0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
31ce0 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
31cf0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
31d00 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29    int (*xCommit)
31d10 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
31d20 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
31d30 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65  Rollback)(sqlite
31d40 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a  3_vtab *pVTab);.
31d50 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e    int (*xFindFun
31d60 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76  ction)(sqlite3_v
31d70 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20  tab *pVtab, int 
31d80 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72  nArg, const char
31d90 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20   *zName,.       
31da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31db0 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28  void (**pxFunc)(
31dc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31dd0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31de0 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20  ue**),.         
31df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
31e00 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69  id **ppArg);.  i
31e10 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71  nt (*xRename)(sq
31e20 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
31e30 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
31e40 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  New);.};../*.** 
31e50 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
31e60 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67  l Table Indexing
31e70 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   Information.** 
31e80 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
31e90 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a  3_index_info.**.
31ea0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
31eb0 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74  ndex_info struct
31ec0 75 72 65 20 61 6e 64 20 69 74 73 20 73 75 62 73  ure and its subs
31ed0 74 72 75 63 74 75 72 65 73 20 69 73 20 75 73 65  tructures is use
31ee0 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20  d as part.** of 
31ef0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
31f00 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  le] interface to
31f10 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61  .** pass informa
31f20 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65  tion into and re
31f30 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79 20  ceive the reply 
31f40 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49  from the [xBestI
31f50 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20  ndex].** method 
31f60 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
31f70 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68  ble module].  Th
31f80 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a  e fields under *
31f90 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68  *Inputs** are th
31fa0 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78  e.** inputs to x
31fb0 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72  BestIndex and ar
31fc0 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42  e read-only.  xB
31fd0 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73  estIndex inserts
31fe0 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20   its.** results 
31ff0 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75  into the **Outpu
32000 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a  ts** fields..**.
32010 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74 72  ** ^(The aConstr
32020 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65 63  aint[] array rec
32030 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75 73  ords WHERE claus
32040 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66  e constraints of
32050 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a   the form:.**.**
32060 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c   <blockquote>col
32070 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f  umn OP expr</blo
32080 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77  ckquote>.**.** w
32090 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c  here OP is =, &l
320a0 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c  t;, &lt;=, &gt;,
320b0 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28   or &gt;=.)^  ^(
320c0 54 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 6f  The particular o
320d0 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74  perator is.** st
320e0 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74 72 61  ored in aConstra
320f0 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f  int[].op using o
32100 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51  ne of the.** [SQ
32110 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32120 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54  RAINT_EQ | SQLIT
32130 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
32140 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a  NT_ values].)^.*
32150 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66  * ^(The index of
32160 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73   the column is s
32170 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e  tored in.** aCon
32180 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d  straint[].iColum
32190 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61  n.)^  ^(aConstra
321a0 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20  int[].usable is 
321b0 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65  TRUE if the.** e
321c0 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74  xpr on the right
321d0 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62  -hand side can b
321e0 65 20 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64  e evaluated (and
321f0 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72   thus the constr
32200 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c  aint.** is usabl
32210 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20  e) and false if 
32220 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a  it cannot.)^.**.
32230 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65  ** ^The optimize
32240 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  r automatically 
32250 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66  inverts terms of
32260 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20   the form "expr 
32270 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e  OP column".** an
32280 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69  d makes other si
32290 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f  mplifications to
322a0 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
322b0 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20  e in an attempt 
322c0 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e  to.** get as man
322d0 79 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  y WHERE clause t
322e0 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f  erms into the fo
322f0 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61  rm shown above a
32300 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e  s possible..** ^
32310 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
32320 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70  ] array only rep
32330 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61 75 73  orts WHERE claus
32340 65 20 74 65 72 6d 73 20 74 68 61 74 20 61 72 65  e terms that are
32350 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20  .** relevant to 
32360 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
32370 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
32380 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
32390 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  * ^Information a
323a0 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42  bout the ORDER B
323b0 59 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72  Y clause is stor
323c0 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d  ed in aOrderBy[]
323d0 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20  ..** ^Each term 
323e0 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f  of aOrderBy reco
323f0 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  rds a column of 
32400 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
32410 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  use..**.** The [
32420 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68  xBestIndex] meth
32430 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f  od must fill aCo
32440 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20  nstraintUsage[] 
32450 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  with information
32460 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70  .** about what p
32470 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73  arameters to pas
32480 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e  s to xFilter.  ^
32490 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74  If argvIndex>0 t
324a0 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74  hen.** the right
324b0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68  -hand side of th
324c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
324d0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73  aConstraint[] is
324e0 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e   evaluated.** an
324f0 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72  d becomes the ar
32500 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79  gvIndex-th entry
32510 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20   in argv.  ^(If 
32520 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
32530 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72  [].omit.** is tr
32540 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  ue, then the con
32550 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d  straint is assum
32560 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68  ed to be fully h
32570 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  andled by the.**
32580 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61   virtual table a
32590 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65  nd is not checke
325a0 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74  d again by SQLit
325b0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e.)^.**.** ^The 
325c0 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74  idxNum and idxPt
325d0 72 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63  r values are rec
325e0 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64  orded and passed
325f0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46   into the.** [xF
32600 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a  ilter] method..*
32610 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  * ^[sqlite3_free
32620 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66  ()] is used to f
32630 72 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e  ree idxPtr if an
32640 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65  d only if.** nee
32650 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73  dToFreeIdxPtr is
32660 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   true..**.** ^Th
32670 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
32680 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74  d means that out
32690 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65  put from [xFilte
326a0 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20  r]/[xNext] will 
326b0 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
326c0 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
326d0 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
326e0 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
326f0 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
32700 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
32710 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
32720 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74  .** ^The estimat
32730 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
32740 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
32750 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
32760 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
32770 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
32780 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
32790 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
327a0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
327b0 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
327c0 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
327d0 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
327e0 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
327f0 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
32800 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
32810 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
32820 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
32830 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
32840 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74   */.  int nConst
32850 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
32860 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
32870 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
32880 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74  aint */.  struct
32890 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
328a0 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20  onstraint {.    
328b0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
328c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
328d0 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e  lumn on left-han
328e0 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72  d side of constr
328f0 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73  aint */.     uns
32900 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20  igned char op;  
32910 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72         /* Constr
32920 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f  aint operator */
32930 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
32940 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20  har usable;     
32950 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20  /* True if this 
32960 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73  constraint is us
32970 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74  able */.     int
32980 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
32990 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
329a0 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
329b0 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
329c0 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  nore */.  } *aCo
329d0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
329e0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66       /* Table of
329f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
32a00 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69  nstraints */.  i
32a10 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
32a20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
32a30 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
32a40 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
32a50 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  use */.  struct 
32a60 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72  sqlite3_index_or
32a70 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74  derby {.     int
32a80 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
32a90 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
32aa0 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20   number */.     
32ab0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65  unsigned char de
32ac0 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  sc;       /* Tru
32ad0 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c  e for DESC.  Fal
32ae0 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20  se for ASC. */. 
32af0 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20   } *aOrderBy;   
32b00 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
32b10 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
32b20 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75  se */.  /* Outpu
32b30 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
32b40 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
32b50 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
32b60 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
32b70 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
32b80 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
32b90 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
32ba0 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
32bb0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
32bc0 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
32bd0 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
32be0 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
32bf0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
32c00 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
32c10 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
32c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32c30 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
32c40 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
32c50 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
32c60 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
32c70 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
32c80 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
32c90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
32ca0 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
32cb0 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
32cc0 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
32cd0 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
32ce0 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
32cf0 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
32d00 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
32d10 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
32d20 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
32d30 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
32d40 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
32d50 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
32d60 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
32d70 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
32d80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32d90 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
32da0 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 65 72 61  Constraint Opera
32db0 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  tor Codes.**.** 
32dc0 54 68 65 73 65 20 6d 61 63 72 6f 73 20 64 65 66  These macros def
32dd0 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f 77 65 64  ined the allowed
32de0 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 0a   values for the.
32df0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 64 65  ** [sqlite3_inde
32e00 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 61  x_info].aConstra
32e10 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e 20  int[].op field. 
32e20 20 45 61 63 68 20 76 61 6c 75 65 20 72 65 70 72   Each value repr
32e30 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 65  esents.** an ope
32e40 72 61 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  rator that is pa
32e50 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 72 61 69  rt of a constrai
32e60 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 65 20 77  nt term in the w
32e70 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66 0a 2a  HERE clause of.*
32e80 2a 20 61 20 71 75 65 72 79 20 74 68 61 74 20 75  * a query that u
32e90 73 65 73 20 61 20 5b 76 69 72 74 75 61 6c 20 74  ses a [virtual t
32ea0 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  able]..*/.#defin
32eb0 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
32ec0 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20  ONSTRAINT_EQ    
32ed0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
32ee0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
32ef0 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e  T_GT    4.#defin
32f00 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43  e SQLITE_INDEX_C
32f10 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20  ONSTRAINT_LE    
32f20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
32f30 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
32f40 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69  T_LT    16.#defi
32f50 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
32f60 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20  CONSTRAINT_GE   
32f70 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   32.#define SQLI
32f80 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32f90 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a  INT_MATCH 64../*
32fa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
32fb0 67 69 73 74 65 72 20 41 20 56 69 72 74 75 61 6c  gister A Virtual
32fc0 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74   Table Implement
32fd0 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ation.**.** ^The
32fe0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
32ff0 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  used to register
33000 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20   a new [virtual 
33010 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61  table module] na
33020 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e  me..** ^Module n
33030 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
33040 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a  istered before.*
33050 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77  * creating a new
33060 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
33070 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c   using the modul
33080 65 20 61 6e 64 20 62 65 66 6f 72 65 20 75 73 69  e and before usi
33090 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74  ng a.** preexist
330a0 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ing [virtual tab
330b0 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  le] for the modu
330c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  le..**.** ^The m
330d0 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65  odule name is re
330e0 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20  gistered on the 
330f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
33100 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a  tion] specified.
33110 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ** by the first 
33120 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
33130 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   name of the mod
33140 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62 79 20  ule is given by 
33150 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70  the .** second p
33160 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20  arameter.  ^The 
33170 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
33180 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
33190 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
331a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69  ation of the [vi
331b0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
331c0 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f 75 72  le].   ^The four
331d0 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  th.** parameter 
331e0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
331f0 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69 6e  client data poin
33200 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73  ter that is pass
33210 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e  ed through.** in
33220 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74 65 5d  to the [xCreate]
33230 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
33240 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 76  methods of the v
33250 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33260 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65  ule.** when a ne
33270 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  w virtual table 
33280 69 73 20 62 65 20 62 65 69 6e 67 20 63 72 65 61  is be being crea
33290 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69 61 6c  ted or reinitial
332a0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ized..**.** ^The
332b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
332c0 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e 74 65  module_v2() inte
332d0 72 66 61 63 65 20 68 61 73 20 61 20 66 69 66 74  rface has a fift
332e0 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  h parameter whic
332f0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
33300 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f  r to a destructo
33310 72 20 66 6f 72 20 74 68 65 20 70 43 6c 69 65 6e  r for the pClien
33320 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 74 65 20  tData.  ^SQLite 
33330 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  will.** invoke t
33340 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
33350 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73  nction (if it is
33360 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20   not NULL) when 
33370 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e  SQLite.** no lon
33380 67 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 43  ger needs the pC
33390 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65  lientData pointe
333a0 72 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  r.  ^The sqlite3
333b0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
333c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
333d0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
333e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
333f0 64 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61  dule_v2() with a
33400 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63   NULL.** destruc
33410 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  tor..*/.int sqli
33420 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
33430 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
33440 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
33450 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
33460 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
33470 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
33480 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
33490 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
334a0 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
334b0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
334c0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c  lite3_module *p,
334d0 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
334e0 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
334f0 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44    void *pClientD
33500 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ata          /* 
33510 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
33520 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
33530 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
33540 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
33550 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
33560 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
33570 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
33580 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
33590 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
335a0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
335b0 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
335c0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
335d0 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
335e0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
335f0 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  p,   /* Methods 
33600 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
33610 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e  /.  void *pClien
33620 74 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f  tData,         /
33630 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
33640 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
33650 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44  ct */.  void(*xD
33660 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20  estroy)(void*)  
33670 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73     /* Module des
33680 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
33690 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
336a0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
336b0 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f  Table Instance O
336c0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
336d0 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a  S: sqlite3_vtab.
336e0 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
336f0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
33700 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
33710 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
33720 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a  s.** of this obj
33730 65 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20  ect to describe 
33740 61 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73  a particular ins
33750 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20  tance.** of the 
33760 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
33770 20 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20    Each subclass 
33780 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f  will.** be tailo
33790 72 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69  red to the speci
337a0 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65  fic needs of the
337b0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
337c0 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70  tation..** The p
337d0 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73  urpose of this s
337e0 75 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20  uperclass is to 
337f0 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66  define certain f
33800 69 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a  ields that are.*
33810 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  * common to all 
33820 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
33830 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56  ations..**.** ^V
33840 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65  irtual tables me
33850 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e  thods can set an
33860 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62   error message b
33870 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a  y assigning a.**
33880 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
33890 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
338a0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72  printf()] to zEr
338b0 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f  rMsg.  The metho
338c0 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65  d should.** take
338d0 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70   care that any p
338e0 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66  rior string is f
338f0 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  reed by a call t
33900 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
33910 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61  )].** prior to a
33920 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73  ssigning a new s
33930 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67  tring to zErrMsg
33940 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72  .  ^After the er
33950 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
33960 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
33970 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
33980 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
33990 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
339a0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
339b0 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
339c0 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
339d0 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
339e0 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73   be zeroed..*/.s
339f0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
33a00 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c  ab {.  const sql
33a10 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f  ite3_module *pMo
33a20 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f  dule;  /* The mo
33a30 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69  dule for this vi
33a40 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20  rtual table */. 
33a50 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20   int nRef;      
33a60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
33a70 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53   /* NO LONGER US
33a80 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45  ED */.  char *zE
33a90 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20  rrMsg;          
33aa0 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
33ab0 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71   message from sq
33ac0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
33ad0 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
33ae0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
33af0 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
33b00 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
33b10 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
33b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33b30 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
33b40 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a  Cursor Object.**
33b50 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
33b60 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
33b70 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75  virtual table cu
33b80 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72  rsor}.**.** Ever
33b90 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  y [virtual table
33ba0 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65   module] impleme
33bb0 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
33bc0 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a  ubclass of the.*
33bd0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  * following stru
33be0 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62  cture to describ
33bf0 65 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70  e cursors that p
33c00 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  oint into the.**
33c10 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
33c20 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a   and are used.**
33c30 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68   to loop through
33c40 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
33c50 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  le.  Cursors are
33c60 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
33c70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
33c80 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f  odule.xOpen | xO
33c90 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74  pen] method of t
33ca0 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72  he module and ar
33cb0 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62  e destroyed.** b
33cc0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  y the [sqlite3_m
33cd0 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78  odule.xClose | x
33ce0 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20  Close] method.  
33cf0 43 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64  Cursors are used
33d00 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c  .** by the [xFil
33d10 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b  ter], [xNext], [
33d20 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d  xEof], [xColumn]
33d30 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d  , and [xRowid] m
33d40 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65  ethods.** of the
33d50 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d   module.  Each m
33d60 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
33d70 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65  tion will define
33d80 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
33d90 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75  of a cursor stru
33da0 63 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74  cture to suit it
33db0 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a  s own needs..**.
33dc0 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61  ** This supercla
33dd0 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64  ss exists in ord
33de0 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65  er to define fie
33df0 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f  lds of the curso
33e00 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f  r that.** are co
33e10 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c  mmon to all impl
33e20 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a  ementations..*/.
33e30 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
33e40 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73  tab_cursor {.  s
33e50 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
33e60 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74  ab;      /* Virt
33e70 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69  ual table of thi
33e80 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a  s cursor */.  /*
33e90 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
33ea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
33eb0 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64  ill typically ad
33ec0 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  d additional fie
33ed0 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  lds */.};../*.**
33ee0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
33ef0 72 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66  re The Schema Of
33f00 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
33f10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72  .**.** ^The [xCr
33f20 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
33f30 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
33f40 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  a.** [virtual ta
33f50 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c  ble module] call
33f60 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a   this interface.
33f70 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68  ** to declare th
33f80 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61  e format (the na
33f90 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65  mes and datatype
33fa0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
33fb0 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74  ) of.** the virt
33fc0 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20  ual tables they 
33fd0 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e  implement..*/.in
33fe0 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
33ff0 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
34000 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51   const char *zSQ
34010 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  L);../*.** CAPI3
34020 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20  REF: Overload A 
34030 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56  Function For A V
34040 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a  irtual Table.**.
34050 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62  ** ^(Virtual tab
34060 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20  les can provide 
34070 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
34080 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66  ementations of f
34090 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e  unctions.** usin
340a0 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63  g the [xFindFunc
340b0 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20  tion] method of 
340c0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
340d0 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a  le module].  .**
340e0 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73   But global vers
340f0 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75  ions of those fu
34100 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20  nctions.** must 
34110 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74  exist in order t
34120 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e  o be overloaded.
34130 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
34140 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
34150 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
34160 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
34170 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
34180 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
34190 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
341a0 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
341b0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
341c0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
341d0 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
341e0 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
341f0 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20  n is created.)^ 
34200 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
34210 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
34220 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
34230 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
34240 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
34250 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
34260 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
34270 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
34280 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
34290 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
342a0 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
342b0 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e   placeholder fun
342c0 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62  ction that can b
342d0 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20  e overloaded.** 
342e0 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  by a [virtual ta
342f0 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ble]..*/.int sql
34300 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75  ite3_overload_fu
34310 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c  nction(sqlite3*,
34320 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
34330 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67  ncName, int nArg
34340 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e  );../*.** The in
34350 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
34360 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
34370 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61  hanism defined a
34380 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a  bove (back up.**
34390 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65   to a comment re
343a0 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72  markably similar
343b0 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73   to this one) is
343c0 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69   currently consi
343d0 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65  dered.** to be e
343e0 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68  xperimental.  Th
343f0 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68  e interface migh
34400 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f  t change in inco
34410 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a  mpatible ways..*
34420 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70  * If this is a p
34430 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20  roblem for you, 
34440 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69  do not use the i
34450 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73  nterface at this
34460 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65   time..**.** Whe
34470 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  n the virtual-ta
34480 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74  ble mechanism st
34490 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c  abilizes, we wil
344a0 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a  l declare the.**
344b0 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64   interface fixed
344c0 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64  , support it ind
344d0 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72  efinitely, and r
344e0 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65  emove this comme
344f0 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt..*/../*.** CA
34500 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65  PI3REF: A Handle
34510 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42   To An Open BLOB
34520 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42  .** KEYWORDS: {B
34530 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f  LOB handle} {BLO
34540 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a  B handles}.**.**
34550 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
34560 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
34570 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42  esents an open B
34580 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20  LOB on which.** 
34590 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
345a0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
345b0 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62   BLOB I/O] can b
345c0 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20  e performed..** 
345d0 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73  ^Objects of this
345e0 20 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65   type are create
345f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
34600 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e  ob_open()].** an
34610 64 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  d destroyed by [
34620 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34630 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b  se()]..** ^The [
34640 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
34650 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
34660 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
34670 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61  interfaces.** ca
34680 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61  n be used to rea
34690 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c  d or write small
346a0 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20   subsections of 
346b0 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68  the BLOB..** ^Th
346c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
346d0 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
346e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  ce returns the s
346f0 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
34700 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70  in bytes..*/.typ
34710 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
34720 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33  te3_blob sqlite3
34730 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _blob;../*.** CA
34740 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42  PI3REF: Open A B
34750 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e  LOB For Incremen
34760 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28  tal I/O.**.** ^(
34770 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20  This interfaces 
34780 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61  opens a [BLOB ha
34790 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74  ndle | handle] t
347a0 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74  o the BLOB locat
347b0 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f  ed.** in row iRo
347c0 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d  w, column zColum
347d0 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20  n, table zTable 
347e0 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b  in database zDb;
347f0 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72  .** in other wor
34800 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f  ds, the same BLO
34810 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20  B that would be 
34820 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a  selected by:.**.
34830 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  ** <pre>.**     
34840 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46  SELECT zColumn F
34850 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57  ROM zDb.zTable W
34860 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69  HERE [rowid] = i
34870 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  Row;.** </pre>)^
34880 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
34890 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69  lags parameter i
348a0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
348b0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
348c0 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20  ned for read.** 
348d0 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73  and write access
348e0 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f  . ^If it is zero
348f0 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70  , the BLOB is op
34900 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63  ened for read ac
34910 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  cess..** ^It is 
34920 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
34930 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
34940 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e  at is part of an
34950 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72   index or primar
34960 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72  y .** key for wr
34970 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65  iting. ^If [fore
34980 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
34990 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  nts] are enabled
349a0 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20  , it is .** not 
349b0 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e  possible to open
349c0 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69   a column that i
349d0 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69  s part of a [chi
349e0 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74  ld key] for writ
349f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ing..**.** ^Note
34a00 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
34a10 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74  se name is not t
34a20 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74  he filename that
34a30 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
34a40 20 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61   database but ra
34a50 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69  ther the symboli
34a60 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  c name of the da
34a70 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61  tabase that.** a
34a80 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65  ppears after the
34a90 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e   AS keyword when
34aa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
34ab0 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67   connected using
34ac0 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46   [ATTACH]..** ^F
34ad0 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  or the main data
34ae0 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64  base file, the d
34af0 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
34b00 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20  "main"..** ^For 
34b10 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65  TEMP tables, the
34b20 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
34b30 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20  s "temp"..**.** 
34b40 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53  ^(On success, [S
34b50 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
34b60 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65  urned and the ne
34b70 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  w [BLOB handle] 
34b80 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f  is written.** to
34b90 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77   *ppBlob. Otherw
34ba0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
34bb0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
34bc0 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73  and *ppBlob is s
34bd0 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75  et.** to be a nu
34be0 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a  ll pointer.)^.**
34bf0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
34c00 73 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61  sets the [databa
34c10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65  se connection] e
34c20 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
34c30 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69  ssage.** accessi
34c40 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ble via [sqlite3
34c50 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20  _errcode()] and 
34c60 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
34c70 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a  )] and related.*
34c80 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f  * functions. ^No
34c90 74 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42  te that the *ppB
34ca0 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20  lob variable is 
34cb0 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a  always initializ
34cc0 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74  ed in a.** way t
34cd0 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66  hat makes it saf
34ce0 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  e to invoke [sql
34cf0 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
34d00 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a  )] on *ppBlob.**
34d10 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
34d20 68 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  he success or fa
34d30 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f  ilure of this ro
34d40 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  utine..**.** ^(I
34d50 66 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61  f the row that a
34d60 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69   BLOB handle poi
34d70 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69  nts to is modifi
34d80 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44  ed by an.** [UPD
34d90 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20  ATE], [DELETE], 
34da0 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49  or by [ON CONFLI
34db0 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73  CT] side-effects
34dc0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f  .** then the BLO
34dd0 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b  B handle is mark
34de0 65 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e  ed as "expired".
34df0 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65  .** This is true
34e00 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f   if any column o
34e10 66 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61  f the row is cha
34e20 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c  nged, even a col
34e30 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  umn.** other tha
34e40 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c  n the one the BL
34e50 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65  OB handle is ope
34e60 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c  n on.)^.** ^Call
34e70 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  s to [sqlite3_bl
34e80 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b  ob_read()] and [
34e90 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
34ea0 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65  te()] for.** a e
34eb0 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64  xpired BLOB hand
34ec0 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  le fail with an 
34ed0 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
34ee0 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a  SQLITE_ABORT]..*
34ef0 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74  * ^(Changes writ
34f00 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  ten into a BLOB 
34f10 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f  prior to the BLO
34f20 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e  B expiring are n
34f30 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  ot.** rolled bac
34f40 6b 20 62 79 20 74 68 65 20 65 78 70 69 72 61 74  k by the expirat
34f50 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ion of the BLOB.
34f60 20 20 53 75 63 68 20 63 68 61 6e 67 65 73 20 77    Such changes w
34f70 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a  ill eventually.*
34f80 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20  * commit if the 
34f90 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
34fa0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
34fb0 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73  ion.)^.**.** ^Us
34fc0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  e the [sqlite3_b
34fd0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
34fe0 65 72 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d  erface to determ
34ff0 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a  ine the size of.
35000 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c  ** the opened bl
35010 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f  ob.  ^The size o
35020 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74  f a blob may not
35030 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 74   be changed by t
35040 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
35050 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44 41  .  Use the [UPDA
35060 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20  TE] SQL command 
35070 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73 69  to change the si
35080 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e  ze of a.** blob.
35090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
350a0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
350b0 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ob()] and [sqlit
350c0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
350d0 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ob()] interfaces
350e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c  .** and the buil
350f0 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20  t-in [zeroblob] 
35100 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  SQL function can
35110 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73   be used, if des
35120 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61  ired,.** to crea
35130 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72  te an empty, zer
35140 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e  o-filled blob in
35150 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f   which to read o
35160 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a  r write using.**
35170 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
35180 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
35190 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c  a resource leak,
351a0 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f   every open [BLO
351b0 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64  B handle] should
351c0 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62   eventually.** b
351d0 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20  e released by a 
351e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
351f0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
35200 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
35210 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69  lob_open(.  sqli
35220 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68  te3*,.  const ch
35230 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74  ar *zDb,.  const
35240 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20   char *zTable,. 
35250 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
35260 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lumn,.  sqlite3_
35270 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e  int64 iRow,.  in
35280 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74  t flags,.  sqlit
35290 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62  e3_blob **ppBlob
352a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
352b0 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f  REF: Close A BLO
352c0 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e  B Handle.**.** ^
352d0 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b  Closes an open [
352e0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a  BLOB handle]..**
352f0 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42  .** ^Closing a B
35300 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20  LOB shall cause 
35310 74 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e  the current tran
35320 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69  saction to commi
35330 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72  t.** if there ar
35340 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73  e no other BLOBs
35350 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65  , no pending pre
35360 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
35370 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74  , and the.** dat
35380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35390 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d   is in [autocomm
353a0 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66  it mode]..** ^If
353b0 20 61 6e 79 20 77 72 69 74 65 73 20 77 65 72 65   any writes were
353c0 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f   made to the BLO
353d0 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20 62 65  B, they might be
353e0 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a   held in cache.*
353f0 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73  * until the clos
35400 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74  e operation if t
35410 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a  hey will fit..**
35420 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68  .** ^(Closing th
35430 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72  e BLOB often for
35440 63 65 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a  ces the changes.
35450 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61  ** out to disk a
35460 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f  nd so if any I/O
35470 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74   errors occur, t
35480 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  hey will likely 
35490 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20  occur.** at the 
354a0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c  time when the BL
354b0 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41  OB is closed.  A
354c0 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  ny errors that o
354d0 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63  ccur during.** c
354e0 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72  losing are repor
354f0 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72  ted as a non-zer
35500 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29  o return value.)
35510 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c  ^.**.** ^(The BL
35520 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63  OB is closed unc
35530 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45  onditionally.  E
35540 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74  ven if this rout
35550 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ine returns.** a
35560 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68  n error code, th
35570 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20  e BLOB is still 
35580 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  closed.)^.**.** 
35590 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
355a0 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c  utine with a nul
355b0 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20  l pointer (such 
355c0 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75  as would be retu
355d0 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69  rned.** by a fai
355e0 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  led call to [sql
355f0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
35600 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  ]) is a harmless
35610 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73   no-op..*/.int s
35620 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
35630 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  e(sqlite3_blob *
35640 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35650 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53  EF: Return The S
35660 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42  ize Of An Open B
35670 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  LOB.**.** ^Retur
35680 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62  ns the size in b
35690 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ytes of the BLOB
356a0 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
356b0 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66  the .** successf
356c0 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f  ully opened [BLO
356d0 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73  B handle] in its
356e0 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
356f0 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65   ^The.** increme
35700 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f  ntal blob I/O ro
35710 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20  utines can only 
35720 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74  read or overwrit
35730 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20  ing existing.** 
35740 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68  blob content; th
35750 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  ey cannot change
35760 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62   the size of a b
35770 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  lob..**.** This 
35780 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
35790 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
357a0 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
357b0 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
357c0 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
357d0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
357e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
357f0 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
35800 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
35810 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
35820 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
35830 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
35840 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
35850 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
35860 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
35870 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
35880 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
35890 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20  ehavior..*/.int 
358a0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
358b0 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  es(sqlite3_blob 
358c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
358d0 52 45 46 3a 20 52 65 61 64 20 44 61 74 61 20 46  REF: Read Data F
358e0 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  rom A BLOB Incre
358f0 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e  mentally.**.** ^
35900 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69  (This function i
35910 73 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 64  s used to read d
35920 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e  ata from an open
35930 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
35940 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  nto a.** caller-
35950 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
35960 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61   N bytes of data
35970 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
35980 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f   buffer Z.** fro
35990 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c  m the open BLOB,
359a0 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66   starting at off
359b0 73 65 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a  set iOffset.)^.*
359c0 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20  *.** ^If offset 
359d0 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
359e0 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f  than N bytes fro
359f0 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
35a00 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54   BLOB,.** [SQLIT
35a10 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
35a20 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
35a30 20 69 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e   is read.  ^If N
35a40 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a   or iOffset is.*
35a50 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
35a60 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
35a70 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
35a80 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
35a90 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f  ..** ^The size o
35aa0 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20  f the blob (and 
35ab0 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75  hence the maximu
35ac0 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66  m value of N+iOf
35ad0 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20  fset).** can be 
35ae0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
35af0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c   the [sqlite3_bl
35b00 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65  ob_bytes()] inte
35b10 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  rface..**.** ^An
35b20 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
35b30 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64   from an expired
35b40 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
35b50 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
35b60 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
35b70 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
35b80 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
35b90 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72  , sqlite3_blob_r
35ba0 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
35bb0 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65  LITE_OK..** Othe
35bc0 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72  rwise, an [error
35bd0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
35be0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
35bf0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
35c00 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ^.**.** This rou
35c10 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
35c20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
35c30 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
35c40 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
35c50 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
35c60 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
35c70 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
35c80 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
35c90 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
35ca0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
35cb0 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
35cc0 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
35cd0 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
35ce0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
35cf0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
35d00 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
35d10 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
35d20 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  vior..**.** See 
35d30 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
35d40 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f  lob_write()]..*/
35d50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
35d60 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
35d70 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20  lob *, void *Z, 
35d80 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73  int N, int iOffs
35d90 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
35da0 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61  3REF: Write Data
35db0 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63   Into A BLOB Inc
35dc0 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a  rementally.**.**
35dd0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
35de0 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74 65  is used to write
35df0 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70   data into an op
35e00 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
35e10 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65   from a.** calle
35e20 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r-supplied buffe
35e30 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 64  r. ^N bytes of d
35e40 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
35e50 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a  rom the buffer Z
35e60 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65  .** into the ope
35e70 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
35e80 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
35e90 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  et..**.** ^If th
35ea0 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  e [BLOB handle] 
35eb0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
35ec0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73  rst argument was
35ed0 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a   not opened for.
35ee0 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20  ** writing (the 
35ef0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
35f00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
35f10 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72  _open()] was zer
35f20 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63  o),.** this func
35f30 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
35f40 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a  LITE_READONLY]..
35f50 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
35f60 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f  tion may only mo
35f70 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  dify the content
35f80 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69  s of the BLOB; i
35f90 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73  t is.** not poss
35fa0 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65  ible to increase
35fb0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42   the size of a B
35fc0 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73 20 41  LOB using this A
35fd0 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65  PI..** ^If offse
35fe0 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
35ff0 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
36000 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
36010 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
36020 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
36030 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
36040 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20  ta is written.  
36050 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73  ^If N is.** less
36060 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49   than zero [SQLI
36070 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
36080 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
36090 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a  a is written..**
360a0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
360b0 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65   BLOB (and hence
360c0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c   the maximum val
360d0 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29  ue of N+iOffset)
360e0 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
360f0 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
36100 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
36110 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
36120 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65  ..**.** ^An atte
36130 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20  mpt to write to 
36140 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
36150 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
36160 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
36170 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
36180 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 73  ABORT].  ^Writes
36190 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61   to the BLOB tha
361a0 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65  t occurred.** be
361b0 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68  fore the [BLOB h
361c0 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61  andle] expired a
361d0 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61  re not rolled ba
361e0 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70  ck by the.** exp
361f0 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68  iration of the h
36200 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66  andle, though of
36210 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68   course those ch
36220 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68  anges might.** h
36230 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69  ave been overwri
36240 74 74 65 6e 20 62 79 20 74 68 65 20 73 74 61 74  tten by the stat
36250 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70 69 72  ement that expir
36260 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  ed the BLOB hand
36270 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65  le.** or by othe
36280 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74  r independent st
36290 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
362a0 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
362b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
362c0 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
362d0 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69  E_OK..** Otherwi
362e0 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63  se, an  [error c
362f0 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65  ode] or an [exte
36300 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
36310 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
36320 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
36330 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e  ne only works on
36340 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d   a [BLOB handle]
36350 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20   which has been 
36360 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20  created.** by a 
36370 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
36380 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36390 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
363a0 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74  nd which has not
363b0 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20  .** been closed 
363c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
363d0 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73  _close()].  Pass
363e0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f  ing any other po
363f0 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74  inter in.** to t
36400 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75  his routine resu
36410 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
36420 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
36430 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
36440 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  or..**.** See al
36450 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  so: [sqlite3_blo
36460 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e  b_read()]..*/.in
36470 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  t sqlite3_blob_w
36480 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  rite(sqlite3_blo
36490 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20  b *, const void 
364a0 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69  *z, int n, int i
364b0 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
364c0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
364d0 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62  l File System Ob
364e0 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69  jects.**.** A vi
364f0 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d  rtual filesystem
36500 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71   (VFS) is an [sq
36510 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
36520 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  t.** that SQLite
36530 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63   uses to interac
36540 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e  t.** with the un
36550 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
36560 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74  ng system.  Most
36570 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63   SQLite builds c
36580 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69  ome with a.** si
36590 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53  ngle default VFS
365a0 20 74 68 61 74 20 69 73 20 61 70 70 72 6f 70 72   that is appropr
365b0 69 61 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73  iate for the hos
365c0 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e  t computer..** N
365d0 65 77 20 56 46 53 65 73 20 63 61 6e 20 62 65 20  ew VFSes can be 
365e0 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 65  registered and e
365f0 78 69 73 74 69 6e 67 20 56 46 53 65 73 20 63 61  xisting VFSes ca
36600 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65 72 65  n be unregistere
36610 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  d..** The follow
36620 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 20 61  ing interfaces a
36630 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a  re provided..**.
36640 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36650 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72  vfs_find() inter
36660 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
36670 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20  ointer to a VFS 
36680 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a  given its name..
36690 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 63 61  ** ^Names are ca
366a0 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a  se sensitive..**
366b0 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f   ^Names are zero
366c0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
366d0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49  8 strings..** ^I
366e0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61  f there is no ma
366f0 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  tch, a NULL poin
36700 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
36710 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65  .** ^If zVfsName
36720 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
36730 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
36740 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
36750 20 5e 4e 65 77 20 56 46 53 65 73 20 61 72 65 20   ^New VFSes are 
36760 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
36770 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
36780 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68  ster()..** ^Each
36790 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73   new VFS becomes
367a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
367b0 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74   if the makeDflt
367c0 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a   flag is set..**
367d0 20 5e 54 68 65 20 73 61 6d 65 20 56 46 53 20 63   ^The same VFS c
367e0 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
367f0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
36800 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a  without injury..
36810 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65  ** ^To make an e
36820 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f  xisting VFS into
36830 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
36840 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61 67  , register it ag
36850 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ain.** with the 
36860 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65  makeDflt flag se
36870 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66 65  t.  If two diffe
36880 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68 20  rent VFSes with 
36890 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65  the.** same name
368a0 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 2c   are registered,
368b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
368c0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20   undefined.  If 
368d0 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69  a.** VFS is regi
368e0 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e 61  stered with a na
368f0 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20  me that is NULL 
36900 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  or an empty stri
36910 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ng,.** then the 
36920 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
36930 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e  fined..**.** ^Un
36940 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77  register a VFS w
36950 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ith the sqlite3_
36960 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
36970 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e   interface..** ^
36980 28 49 66 20 74 68 65 20 64 65 66 61 75 6c 74 20  (If the default 
36990 56 46 53 20 69 73 20 75 6e 72 65 67 69 73 74 65  VFS is unregiste
369a0 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53  red, another VFS
369b0 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a   is chosen as.**
369c0 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54   the default.  T
369d0 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68  he choice for th
369e0 65 20 6e 65 77 20 56 46 53 20 69 73 20 61 72 62  e new VFS is arb
369f0 69 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c  itrary.)^.*/.sql
36a00 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65  ite3_vfs *sqlite
36a10 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74  3_vfs_find(const
36a20 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29   char *zVfsName)
36a30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
36a40 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69 74  s_register(sqlit
36a50 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b  e3_vfs*, int mak
36a60 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69  eDflt);.int sqli
36a70 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
36a80 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29  er(sqlite3_vfs*)
36a90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36aa0 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a  F: Mutexes.**.**
36ab0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
36ac0 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
36ad0 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a  ines for thread.
36ae0 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69  ** synchronizati
36af0 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20  on. Though they 
36b00 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
36b10 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65   internal.** use
36b20 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65   by SQLite, code
36b30 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
36b40 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  nst SQLite is.**
36b50 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73   permitted to us
36b60 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
36b70 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
36b80 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
36b90 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d   code contains m
36ba0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
36bb0 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68  tations.** of th
36bc0 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ese mutex routin
36bd0 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69  es.  An appropri
36be0 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ate implementati
36bf0 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65  on.** is selecte
36c00 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
36c10 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e  at compile-time.
36c20 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
36c30 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  g.** implementat
36c40 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62  ions are availab
36c50 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  le in the SQLite
36c60 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   core:.**.** <ul
36c70 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  >.** <li>   SQLI
36c80 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20  TE_MUTEX_OS2.** 
36c90 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
36ca0 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c  TEX_PTHREAD.** <
36cb0 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
36cc0 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20  EX_W32.** <li>  
36cd0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f   SQLITE_MUTEX_NO
36ce0 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  OP.** </ul>)^.**
36cf0 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
36d00 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65  MUTEX_NOOP imple
36d10 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73  mentation is a s
36d20 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a  et of routines.*
36d30 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72  * that does no r
36d40 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20  eal locking and 
36d50 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
36d60 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73  or use in.** a s
36d70 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61  ingle-threaded a
36d80 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68  pplication.  ^Th
36d90 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f  e SQLITE_MUTEX_O
36da0 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55  S2,.** SQLITE_MU
36db0 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64  TEX_PTHREAD, and
36dc0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33   SQLITE_MUTEX_W3
36dd0 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  2 implementation
36de0 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72  s.** are appropr
36df0 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20  iate for use on 
36e00 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20  OS/2, Unix, and 
36e10 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e  Windows..**.** ^
36e20 28 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  (If SQLite is co
36e30 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
36e40 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50  SQLITE_MUTEX_APP
36e50 44 45 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72  DEF preprocessor
36e60 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  .** macro define
36e70 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54  d (with "-DSQLIT
36e80 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31  E_MUTEX_APPDEF=1
36e90 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65  "), then no mute
36ea0 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  x.** implementat
36eb0 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20  ion is included 
36ec0 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
36ed0 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20 74  . In this case t
36ee0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
36ef0 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
36f00 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70  custom mutex imp
36f10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e  lementation usin
36f20 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
36f30 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f  _CONFIG_MUTEX] o
36f40 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c  ption of the sql
36f50 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75  ite3_config() fu
36f60 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65  nction.** before
36f70 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
36f80 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72  _initialize() or
36f90 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69   any other publi
36fa0 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75  c sqlite3_.** fu
36fb0 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c  nction that call
36fc0 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
36fd0 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  lize().)^.**.** 
36fe0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
36ff0 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  ex_alloc() routi
37000 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e  ne allocates a n
37010 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20  ew.** mutex and 
37020 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37030 72 20 74 6f 20 69 74 2e 20 5e 49 66 20 69 74 20  r to it. ^If it 
37040 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20  returns NULL.** 
37050 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20  that means that 
37060 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f  a mutex could no
37070 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20  t be allocated. 
37080 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c   ^SQLite.** will
37090 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63   unwind its stac
370a0 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20  k and return an 
370b0 65 72 72 6f 72 2e 20 20 5e 28 54 68 65 20 61 72  error.  ^(The ar
370c0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
370d0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
370e0 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  () is one of the
370f0 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
37100 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ants:.**.** <ul>
37110 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
37120 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c  _MUTEX_FAST.** <
37130 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
37140 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c  X_RECURSIVE.** <
37150 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
37160 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a  X_STATIC_MASTER.
37170 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
37180 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
37190 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
371a0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
371b0 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  M2.** <li>  SQLI
371c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
371d0 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  PRNG.** <li>  SQ
371e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
371f0 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53  C_LRU.** <li>  S
37200 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
37210 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e  IC_LRU2.** </ul>
37220 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  )^.**.** ^The fi
37230 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  rst two constant
37240 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  s (SQLITE_MUTEX_
37250 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f  FAST and SQLITE_
37260 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
37270 0a 2a 2a 20 63 61 75 73 65 20 73 71 6c 69 74 65  .** cause sqlite
37280 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20  3_mutex_alloc() 
37290 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e  to create.** a n
372a0 65 77 20 6d 75 74 65 78 2e 20 20 5e 54 68 65 20  ew mutex.  ^The 
372b0 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 65 63  new mutex is rec
372c0 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49  ursive when SQLI
372d0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
372e0 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75  VE.** is used bu
372f0 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c  t not necessaril
37300 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45  y so when SQLITE
37310 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20 75  _MUTEX_FAST is u
37320 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65  sed..** The mute
37330 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
37340 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
37350 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63  o make a distinc
37360 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
37370 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
37380 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54  URSIVE and SQLIT
37390 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20  E_MUTEX_FAST if 
373a0 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  it does.** not w
373b0 61 6e 74 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65  ant to.  ^SQLite
373c0 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65   will only reque
373d0 73 74 20 61 20 72 65 63 75 72 73 69 76 65 20 6d  st a recursive m
373e0 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73  utex in.** cases
373f0 20 77 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79   where it really
37400 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66   needs one.  ^If
37410 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65   a faster non-re
37420 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a  cursive mutex.**
37430 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37440 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20  is available on 
37450 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72  the host platfor
37460 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62  m, the mutex sub
37470 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20  system.** might 
37480 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75  return such a mu
37490 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  tex in response 
374a0 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  to SQLITE_MUTEX_
374b0 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  FAST..**.** ^The
374c0 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70   other allowed p
374d0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c  arameters to sql
374e0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
374f0 28 29 20 28 61 6e 79 74 68 69 6e 67 20 6f 74 68  () (anything oth
37500 65 72 0a 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54  er.** than SQLIT
37510 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64  E_MUTEX_FAST and
37520 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
37530 43 55 52 53 49 56 45 29 20 65 61 63 68 20 72 65  CURSIVE) each re
37540 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  turn.** a pointe
37550 72 20 74 6f 20 61 20 73 74 61 74 69 63 20 70 72  r to a static pr
37560 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e  eexisting mutex.
37570 20 20 5e 53 69 78 20 73 74 61 74 69 63 20 6d 75    ^Six static mu
37580 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  texes are.** use
37590 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  d by the current
375a0 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
375b0 74 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  te.  Future vers
375c0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
375d0 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69  * may add additi
375e0 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65  onal static mute
375f0 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74  xes.  Static mut
37600 65 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74  exes are for int
37610 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
37620 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70  SQLite only.  Ap
37630 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
37640 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78  use SQLite mutex
37650 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65  es should.** use
37660 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69   only the dynami
37670 63 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e  c mutexes return
37680 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54  ed by SQLITE_MUT
37690 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51  EX_FAST or.** SQ
376a0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
376b0 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  SIVE..**.** ^Not
376c0 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66  e that if one of
376d0 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
376e0 65 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53  ex parameters (S
376f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
37700 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55  .** or SQLITE_MU
37710 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69  TEX_RECURSIVE) i
37720 73 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69  s used then sqli
37730 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
37740 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64  ).** returns a d
37750 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f  ifferent mutex o
37760 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e  n every call.  ^
37770 42 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74  But for the stat
37780 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65  ic.** mutex type
37790 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65  s, the same mute
377a0 78 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e  x is returned on
377b0 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74   every call that
377c0 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65   has.** the same
377d0 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a   type number..**
377e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
377f0 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f  _mutex_free() ro
37800 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65  utine deallocate
37810 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  s a previously.*
37820 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61  * allocated dyna
37830 6d 69 63 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c  mic mutex.  ^SQL
37840 69 74 65 20 69 73 20 63 61 72 65 66 75 6c 20 74  ite is careful t
37850 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65  o deallocate eve
37860 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75  ry.** dynamic mu
37870 74 65 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f  tex that it allo
37880 63 61 74 65 73 2e 20 20 54 68 65 20 64 79 6e 61  cates.  The dyna
37890 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74  mic mutexes must
378a0 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73   not be in.** us
378b0 65 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  e when they are 
378c0 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74  deallocated.  At
378d0 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c  tempting to deal
378e0 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69 63 0a  locate a static.
378f0 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73  ** mutex results
37900 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
37910 68 61 76 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65  havior.  ^SQLite
37920 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74   never deallocat
37930 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d  es.** a static m
37940 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  utex..**.** ^The
37950 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
37960 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74  nter() and sqlit
37970 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72  e3_mutex_try() r
37980 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a  outines attempt.
37990 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75  ** to enter a mu
379a0 74 65 78 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65  tex.  ^If anothe
379b0 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72 65  r thread is alre
379c0 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d  ady within the m
379d0 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  utex,.** sqlite3
379e0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77  _mutex_enter() w
379f0 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71  ill block and sq
37a00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
37a10 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
37a20 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e   SQLITE_BUSY.  ^
37a30 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
37a40 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61 63  x_try() interfac
37a50 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
37a60 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75  E_OK].** upon su
37a70 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20  ccessful entry. 
37a80 20 5e 28 4d 75 74 65 78 65 73 20 63 72 65 61 74   ^(Mutexes creat
37a90 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ed using.** SQLI
37aa0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
37ab0 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65  VE can be entere
37ac0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
37ad0 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
37ae0 65 61 64 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20  ead..** In such 
37af0 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75  cases the,.** mu
37b00 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 69 74  tex must be exit
37b10 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62  ed an equal numb
37b20 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f  er of times befo
37b30 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  re another threa
37b40 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29  d.** can enter.)
37b50 5e 20 20 5e 28 49 66 20 74 68 65 20 73 61 6d 65  ^  ^(If the same
37b60 20 74 68 72 65 61 64 20 74 72 69 65 73 20 74 6f   thread tries to
37b70 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72   enter any other
37b80 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65  .** kind of mute
37b90 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  x more than once
37ba0 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
37bb0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
37bc0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
37bd0 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63  r exhibit.** suc
37be0 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74  h behavior in it
37bf0 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74  s own use of mut
37c00 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  exes.)^.**.** ^(
37c10 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f  Some systems (fo
37c20 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f  r example, Windo
37c30 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75  ws 95) do not su
37c40 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74  pport the operat
37c50 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
37c60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75  ed by sqlite3_mu
37c70 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74  tex_try().  On t
37c80 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71  hose systems, sq
37c90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
37ca0 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73  ).** will always
37cb0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42   return SQLITE_B
37cc0 55 53 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65  USY.  The SQLite
37cd0 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20   core only ever 
37ce0 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  uses.** sqlite3_
37cf0 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73 20 61  mutex_try() as a
37d00 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73  n optimization s
37d10 6f 20 74 68 69 73 20 69 73 20 61 63 63 65 70 74  o this is accept
37d20 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 29 5e  able behavior.)^
37d30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37d40 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
37d50 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20  ) routine exits 
37d60 61 20 6d 75 74 65 78 20 74 68 61 74 20 77 61 73  a mutex that was
37d70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65  .** previously e
37d80 6e 74 65 72 65 64 20 62 79 20 74 68 65 20 73 61  ntered by the sa
37d90 6d 65 20 74 68 72 65 61 64 2e 20 20 20 5e 28 54  me thread.   ^(T
37da0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
37db0 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74  s undefined if t
37dc0 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20  he mutex is not 
37dd0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
37de0 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  d by the.** call
37df0 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73  ing thread or is
37e00 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61   not currently a
37e10 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74  llocated.  SQLit
37e20 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20  e will.** never 
37e30 64 6f 20 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a  do either.)^.**.
37e40 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d  ** ^If the argum
37e50 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ent to sqlite3_m
37e60 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71  utex_enter(), sq
37e70 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
37e80 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  ), or.** sqlite3
37e90 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69  _mutex_leave() i
37ea0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
37eb0 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65  , then all three
37ec0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68   routines.** beh
37ed0 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  ave as no-ops..*
37ee0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
37ef0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
37f00 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ld()] and [sqlit
37f10 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
37f20 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ()]..*/.sqlite3_
37f30 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d  mutex *sqlite3_m
37f40 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b  utex_alloc(int);
37f50 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75  .void sqlite3_mu
37f60 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33  tex_free(sqlite3
37f70 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73  _mutex*);.void s
37f80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
37f90 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  er(sqlite3_mutex
37fa0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37fb0 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65  mutex_try(sqlite
37fc0 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20  3_mutex*);.void 
37fd0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
37fe0 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ave(sqlite3_mute
37ff0 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x*);../*.** CAPI
38000 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68  3REF: Mutex Meth
38010 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
38020 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
38030 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 64  this structure d
38040 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c  efines the low-l
38050 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  evel routines.**
38060 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74   used to allocat
38070 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65  e and use mutexe
38080 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79  s..**.** Usually
38090 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  , the default mu
380a0 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
380b0 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62 79 20  ons provided by 
380c0 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75  SQLite are.** su
380d0 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65  fficient, howeve
380e0 72 20 74 68 65 20 75 73 65 72 20 68 61 73 20 74  r the user has t
380f0 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62  he option of sub
38100 73 74 69 74 75 74 69 6e 67 20 61 20 63 75 73 74  stituting a cust
38110 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  om.** implementa
38120 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c  tion for special
38130 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73  ized deployments
38140 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20   or systems for 
38150 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20  which SQLite.** 
38160 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
38170 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
38180 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74  ementation. In t
38190 68 69 73 20 63 61 73 65 2c 20 74 68 65 20 75 73  his case, the us
381a0 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e  er.** creates an
381b0 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69  d populates an i
381c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
381d0 73 74 72 75 63 74 75 72 65 20 74 6f 20 70 61 73  structure to pas
381e0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
381f0 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77  config() along w
38200 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
38210 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70  CONFIG_MUTEX] op
38220 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  tion..** Additio
38230 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e  nally, an instan
38240 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
38250 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
38260 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74   as an.** output
38270 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71   variable when q
38280 75 65 72 79 69 6e 67 20 74 68 65 20 73 79 73 74  uerying the syst
38290 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  em for the curre
382a0 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  nt mutex.** impl
382b0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e  ementation, usin
382c0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
382d0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f  NFIG_GETMUTEX] o
382e0 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ption..**.** ^Th
382f0 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
38300 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74  hod defined by t
38310 68 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73  his structure is
38320 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70   invoked as.** p
38330 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e  art of system in
38340 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20  itialization by 
38350 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  the sqlite3_init
38360 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  ialize() functio
38370 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  n..** ^The xMute
38380 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20 69 73  xInit routine is
38390 20 63 61 6c 6c 65 20 62 79 20 53 51 4c 69 74 65   calle by SQLite
383a0 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f   exactly once fo
383b0 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74  r each.** effect
383c0 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ive call to [sql
383d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
383e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
383f0 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20  MutexEnd method 
38400 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
38410 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
38420 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
38430 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f  of system shutdo
38440 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  wn by the sqlite
38450 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e  3_shutdown() fun
38460 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d  ction. The.** im
38470 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
38480 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65  this method is e
38490 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61  xpected to relea
384a0 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69  se all outstandi
384b0 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ng.** resources 
384c0 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
384d0 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d  mutex methods im
384e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73  plementation, es
384f0 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73  pecially.** thos
38500 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  e obtained by th
38510 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74  e xMutexInit met
38520 68 6f 64 2e 20 20 5e 54 68 65 20 78 4d 75 74 65  hod.  ^The xMute
38530 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66  xEnd().** interf
38540 61 63 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 65  ace is invoked e
38550 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20  xactly once for 
38560 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  each call to [sq
38570 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
38580 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72  ]..**.** ^(The r
38590 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d  emaining seven m
385a0 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62  ethods defined b
385b0 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
385c0 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a   (xMutexAlloc,.*
385d0 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d  * xMutexFree, xM
385e0 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65  utexEnter, xMute
385f0 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76  xTry, xMutexLeav
38600 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e  e, xMutexHeld an
38610 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65  d.** xMutexNothe
38620 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  ld) implement th
38630 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  e following inte
38640 72 66 61 63 65 73 20 28 72 65 73 70 65 63 74 69  rfaces (respecti
38650 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  vely):.**.** <ul
38660 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
38670 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
38680 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20  c()] </li>.**   
38690 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d  <li>  [sqlite3_m
386a0 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c  utex_free()] </l
386b0 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
386c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
386d0 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  er()] </li>.**  
386e0 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
386f0 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c  mutex_try()] </l
38700 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73  i>.**   <li>  [s
38710 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
38720 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20  ve()] </li>.**  
38730 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
38740 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f  mutex_held()] </
38750 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  li>.**   <li>  [
38760 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
38770 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  theld()] </li>.*
38780 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
38790 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
387a0 6e 63 65 20 69 73 20 74 68 61 74 20 74 68 65 20  nce is that the 
387b0 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58  public sqlite3_X
387c0 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75  XX functions enu
387d0 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65  merated.** above
387e0 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
387f0 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73   any invocations
38800 20 74 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c   that pass a NUL
38810 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  L pointer instea
38820 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20  d.** of a valid 
38830 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68  mutex handle. Th
38840 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
38850 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73  s of the methods
38860 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74   defined.** by t
38870 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61 72  his structure ar
38880 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74  e not required t
38890 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61  o handle this ca
388a0 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a  se, the results.
388b0 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20  ** of passing a 
388c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73  NULL pointer ins
388d0 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20  tead of a valid 
388e0 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65  mutex handle are
388f0 20 75 6e 64 65