/ Hex Artifact Content
Login

Artifact f9a9be1bce911669a259f7c747bf05635cb360b5:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
16d0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
16e0: 4f 4e 5f 44 49 41 47 53 0a 2f 2a 0a 2a 2a 20 43  ON_DIAGS./*.** C
16f0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1700: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
1710: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
1720: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
1730: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
1740: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1750: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
1760: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1770: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1780: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1790: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
17a0: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
17b0: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
17c0: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
17d0: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
17e0: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
17f0: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1800: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1810: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
1820: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1830: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1840: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
1850: 6c 6f 77 73 20 69 6e 74 65 72 61 74 69 6e 67 0a  lows interating.
1860: 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74  ** over the list
1870: 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74   of options that
1880: 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74   were defined at
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79   compile time by
18a0: 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68  .** returning th
18b0: 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74  e N-th compile t
18c0: 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e  ime option strin
18d0: 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74  g.  ^If N is out
18e0: 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71   of range,.** sq
18f0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1900: 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e  ion_get() return
1910: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1920: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
1930: 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d  .** prefix is om
1940: 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73  itted from any s
1950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1960: 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  by .** sqlite3_c
1970: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1980: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f  ()..**.** ^Suppo
1990: 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e  rt for the diagn
19a0: 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20  ostic functions 
19b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
19c0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20  ption_used().** 
19d0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  and sqlite3_comp
19e0: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
19f0: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62  may be omitted b
1a00: 79 20 73 70 65 63 69 66 69 6e 67 20 74 68 65 20  y specifing the 
1a10: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1a20: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1a30: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1a40: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1a50: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1a60: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1a90: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1aa0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1ab0: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1ac0: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1ad0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 20 2f 2a  nt N);.#endif /*
1b40: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b50: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b60: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1b70: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
1b80: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
1b90: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
1ba0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bb0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1bc0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1bd0: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1be0: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1bf0: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69   compiled mutexi
1c00: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1c10: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c30: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c40: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c50: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c60: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c70: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c80: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c90: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1ca0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1cb0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1cc0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cd0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1ce0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cf0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1d00: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1d10: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d20: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d30: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d40: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d50: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d60: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d70: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d80: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d90: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1da0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1db0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1dc0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1dd0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1de0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1df0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1e00: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1e10: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e20: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e30: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e40: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e50: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e60: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e70: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e80: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e90: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1ea0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1eb0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ec0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1ed0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ee0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ef0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1f00: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1f10: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f20: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f30: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f40: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f50: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f60: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f70: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f80: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1fa0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1fb0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fc0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fd0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fe0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1ff0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2000: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2010: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2020: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2030: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2040: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2050: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2060: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2070: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2080: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
20a0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
20b0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20c0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20e0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20f0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2100: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2110: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2120: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2130: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2140: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2150: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2160: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2170: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2180: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2190: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
21a0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
21b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21c0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21d0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21e0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21f0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2200: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2210: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2220: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2230: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2240: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2250: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2260: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2270: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2280: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2290: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
22a0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
22b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22c0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22d0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22e0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22f0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2300: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2310: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2320: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2330: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2340: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2350: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2360: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2370: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2380: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2390: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
23a0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
23b0: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23c0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23d0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23e0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23f0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2400: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
2410: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2420: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2430: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2440: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2450: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2460: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2470: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2480: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2490: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
24a0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
24b0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24c0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24d0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24f0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2500: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2510: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2520: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2530: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2540: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2550: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2560: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2570: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2580: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2590: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
25a0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
25b0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25c0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25d0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25e0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25f0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2600: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2610: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2620: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2630: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2640: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2650: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2660: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2670: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2680: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2690: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26a0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
26b0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26c0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26d0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26e0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26f0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2700: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2710: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2720: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2730: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2740: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2750: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2760: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2770: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2780: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2790: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
27a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
27b0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27c0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27d0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27f0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2800: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2810: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2820: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2830: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2840: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2850: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2860: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2870: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2890: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
28a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
28b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28e0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28f0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2900: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2910: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2930: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2940: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2950: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2960: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2970: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2980: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2990: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
29a0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
29b0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29c0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29d0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29f0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2a00: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2a10: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a20: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a40: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a50: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a60: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a70: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a80: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a90: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2aa0: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2ab0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2ac0: 20 73 75 63 63 65 73 73 66 75 6c 6c 6c 79 20 64   successfullly d
2ad0: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
2ae0: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
2af0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b00: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
2b10: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2b20: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2b30: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2b40: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b50: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
2b60: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2b70: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2b80: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
2b90: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
2ba0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2bb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2bc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2bd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2be0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2bf0: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
2c00: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2c10: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2c20: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2c30: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2c40: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2c50: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
2c60: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
2c70: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
2c80: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
2ca0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
2cb0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2cc0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
2cd0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
2ce0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2cf0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
2d00: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
2d10: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2d20: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
2d30: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
2d40: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
2d50: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
2d60: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
2d70: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
2d80: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2d90: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
2da0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2db0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
2dc0: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
2dd0: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
2de0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
2df0: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2e00: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
2e10: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
2e20: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
2e30: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2e40: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2e50: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
2e60: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
2e70: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
2e80: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
2e90: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
2ea0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
2eb0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2ec0: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2ed0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2ee0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2ef0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2f00: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2f10: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f20: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2f30: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2f40: 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68  terface.**.** Th
2f50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2f60: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
2f70: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
2f80: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
2f90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2fa0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2fb0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2fc0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2fd0: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73  ,.** that allows
2fe0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2ff0: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20  to run multiple 
3000: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51  statements of SQ
3010: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76  L.** without hav
3020: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74  ing to use a lot
3030: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a   of C code. .**.
3040: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
3050: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
3060: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   runs zero or mo
3070: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  re UTF-8 encoded
3080: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ,.** semicolon-s
3090: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74  eparate SQL stat
30a0: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
30b0: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  to its 2nd argum
30c0: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63  ent,.** in the c
30d0: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
30e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30f0: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73  on] passed in as
3100: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75   its 1st.** argu
3110: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63  ment.  ^If the c
3120: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3130: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75   of the 3rd argu
3140: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
3150: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3160: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69   NULL, then it i
3170: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61  s invoked for ea
3180: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a  ch result row.**
3190: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74   coming out of t
31a0: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c  he evaluated SQL
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54   statements.  ^T
31c0: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
31d0: 74 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  to.** to sqlite3
31e0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
31f0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
3200: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
3210: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3220: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3230: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3240: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3250: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3260: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3270: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3280: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3290: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
32a0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
32b0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
32c0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
32d0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
32e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
32f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3300: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
3310: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3320: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3330: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3340: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3350: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3360: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3370: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3380: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3390: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
33a0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
33b0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
33c0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
33d0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
33e0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
33f0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
3400: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3410: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3420: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3430: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3440: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3450: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3460: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3470: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3480: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3490: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
34a0: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
34b0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
34c0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
34d0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
34e0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
34f0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3500: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3510: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3520: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3530: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3540: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3550: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3560: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3570: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3580: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3590: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
35a0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
35b0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
35c0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
35d0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
35e0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
35f0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3600: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3610: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3620: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3630: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3640: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3650: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3660: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3670: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3680: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3690: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
36a0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
36b0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
36c0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
36d0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
36e0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
36f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3700: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3710: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3720: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3730: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3740: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3750: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3760: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3770: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3780: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3790: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
37a0: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
37b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37c0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
37d0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
37e0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
37f0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3800: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3810: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3820: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3830: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3840: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3850: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3860: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3870: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3880: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3890: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
38a0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
38b0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
38c0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
38d0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
38e0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
38f0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3900: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3910: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3920: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3930: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3940: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3950: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3970: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3980: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3990: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
39a0: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
39b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
39c0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
39d0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
39e0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
39f0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3a00: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3a10: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3a20: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3a30: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3a40: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3a50: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3a60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3a70: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3a80: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3a90: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3aa0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ab0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3ac0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3ad0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3ae0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3af0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3b00: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3b10: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3b20: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3b30: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3b40: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3b50: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3b60: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3b70: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3b80: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3b90: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bb0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
3bc0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
3bd0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
3be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bf0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
3c00: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
3c10: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
3c20: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3c30: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
3c40: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
3c50: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
3c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
3c90: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
3ca0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
3cb0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
3cc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3cd0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
3ce0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
3cf0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3d00: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
3d10: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3d20: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3d30: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3d40: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
3d50: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
3d60: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
3d70: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
3d80: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
3d90: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
3da0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
3db0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
3dc0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
3dd0: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66  tes success or f
3de0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3df0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3e00: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3e10: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3e20: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3e30: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3e40: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3e50: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3e60: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  des].*/.#define 
3e70: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
3e80: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
3e90: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
3ea0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
3eb0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
3ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
3ed0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
3ee0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
3ef0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3f00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3f10: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3f20: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
3f30: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
3f40: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
3f50: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
3f60: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
3f70: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
3f80: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
3f90: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
3fa0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
3fb0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
3fc0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
3fd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fe0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
3ff0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4000: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
4010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4020: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4030: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4040: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4050: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4070: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4080: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
40a0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
40b0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
40c0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
40d0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
40e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
40f0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4100: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
4110: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4120: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4140: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4150: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4160: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4170: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4180: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4190: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
41a0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
41b0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
41c0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
41d0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
41e0: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
41f0: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
4200: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
4210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
4220: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
4230: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
4240: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
4250: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
4260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
4270: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
4280: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
4290: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
42a0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
42b0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
42c0: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
42d0: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
42e0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4300: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
4310: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
4320: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4330: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4340: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4350: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4360: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4380: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4390: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
43a0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
43b0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
43c0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43d0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43e0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43f0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
4400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
4410: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
4420: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4430: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4440: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4450: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4460: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4470: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4480: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4490: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
44a0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
44b0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
44c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44d0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44e0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44f0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4500: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
4510: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
4520: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4530: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4560: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4570: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4580: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4590: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
45a0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
45b0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
45c0: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45f0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4600: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4610: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4620: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4640: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4650: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4660: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4670: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4680: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4690: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
46a0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
46b0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
46c0: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46d0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46e0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46f0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
4700: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4710: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4720: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4730: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4740: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4750: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4760: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4770: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4780: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4790: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
47a0: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
47b0: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
47c0: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47d0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47e0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47f0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
4800: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
4810: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
4820: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4830: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4840: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4850: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4860: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4870: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4880: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4890: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
48a0: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
48b0: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
48c0: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48d0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48e0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48f0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
4900: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
4910: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4920: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4930: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4940: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4950: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4960: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4970: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4980: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4990: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
49a0: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
49b0: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
49c0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49d0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49e0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49f0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
4a00: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a10: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
4a20: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a30: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a40: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a50: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a60: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a70: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a80: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a90: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4aa0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4ab0: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4ac0: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4ad0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ae0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4af0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4b10: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b30: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b50: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b70: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b90: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4ba0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4bb0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4bc0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4bd0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4be0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bf0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4c00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4c10: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4c20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c30: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c50: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c70: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c90: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4ca0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4cb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4cc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4cd0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4ce0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cf0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4d00: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4d10: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4d20: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d40: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d50: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d80: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d90: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4da0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4db0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dc0: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4dd0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4de0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4df0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e00: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4e10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e40: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e50: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e90: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4eb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ec0: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ed0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4ee0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ef0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f00: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4f10: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4f20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f40: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4f50: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4f60: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c  TE_LOCKED | (1<<
4f70: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  8) )../*.** CAPI
4f80: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
4f90: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
4fa0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
4fb0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
4fc0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
4fd0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
4fe0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4ff0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5000: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5010: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5020: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5030: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
5040: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
5050: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5080: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5090: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
50a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
50d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
50e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
50f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5110: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5120: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5130: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5140: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5170: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5180: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
51b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
51c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
51d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51e0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
51f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5220: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5230: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5240: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5260: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5270: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5280: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52a0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
52b0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
52c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
52d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52e0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
52f0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
5300: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5320: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5330: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5340: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5360: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5370: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5380: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53a0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
53b0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
53c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
53d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53e0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
53f0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5400: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5410: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5430: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5440: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5450: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5460: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5480: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5490: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
54a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
54b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54d0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
54e0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
54f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5500: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5510: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5520: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5530: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5540: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
5550: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
5560: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5570: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
5580: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
5590: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
55a0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
55b0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
55c0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
55d0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
55e0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
55f0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
5600: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
5610: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
5620: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5630: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
5640: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5650: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
5660: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5670: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
5680: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
5690: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
56a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
56b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
56c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
56d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
56e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
56f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5700: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5710: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5720: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5730: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5740: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5750: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5760: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
5770: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
5780: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5790: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
57a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
57b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
57c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
57d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
57e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
57f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5800: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5810: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5820: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5830: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5840: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5850: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
5860: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
5870: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
5880: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5890: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
58a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
58b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
58d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
58e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5900: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5920: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
5930: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
5940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5950: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
5960: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5980: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
5990: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
59a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
59c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
59f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5a00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a10: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5a20: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5a50: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30  D     0x00000200
5a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a70: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5a80: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5a90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5aa0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
5ab0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
5ac0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
5ad0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5ae0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5af0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
5b00: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
5b10: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
5b20: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
5b30: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
5b40: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5b50: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
5b60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5b70: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
5b80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5b90: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
5ba0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
5bb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
5bc0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
5bd0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
5be0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
5bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5c00: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
5c10: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
5c20: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
5c30: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
5c40: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
5c50: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
5c60: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
5c70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5c80: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5c90: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
5ca0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
5cb0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5cc0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
5cd0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
5ce0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
5cf0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5d00: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5d10: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5d20: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
5d30: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5d40: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5d50: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
5d60: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
5d70: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
5d80: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
5d90: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
5da0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
5db0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5dc0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
5dd0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
5de0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
5df0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
5e00: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
5e10: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5e20: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
5e30: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
5e40: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5e50: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
5e60: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5e70: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5e80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5e90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5ea0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
5eb0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
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 20 20 20 20 20 30 78 30 30  TAONLY      0x00
5ee0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
5ef0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5f00: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5f10: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
5f20: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
5f30: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
5f40: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
5f50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
5f60: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
5f70: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
5f80: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
5f90: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
5fa0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
5fb0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
5fc0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
5fd0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
5fe0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
5ff0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
6000: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
6010: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
6020: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
6030: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6040: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
6050: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
6060: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
6070: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
6080: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
6090: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
60a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
60b0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
60c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
60d0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
60e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
60f0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
6100: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
6110: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
6120: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6130: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
6140: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
6150: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
6160: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
6170: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
6180: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
6190: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
61a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
61b0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
61c0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
61d0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
61e0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
61f0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
6200: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
6210: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
6220: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
6230: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
6240: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
6250: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
6260: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
6270: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
6280: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
6290: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
62a0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
62b0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f  .**.** If the xO
62c0: 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20  pen method sets 
62d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
62e0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
62f0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
6300: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
6310: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
6320: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
6330: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
6340: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
6350: 20 74 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72   the xOpen repor
6360: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
6370: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
6380: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
6390: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
63a0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
63b0: 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20  led xOpen.** is 
63c0: 66 6f 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f  for the xOpen to
63d0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
63e0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
63f0: 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a  lement to NULL..
6400: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
6410: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
6420: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
6430: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
6440: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
6450: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
6460: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
6470: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
6480: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
6490: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
64a0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
64b0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
64c0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
64d0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
64e0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
64f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
6500: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
6510: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
6520: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
6530: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
6540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
6550: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
6560: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6570: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
6580: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
6590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
65a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
65b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
65c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65d0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
65e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
65f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
6600: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
6610: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6620: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
6630: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
6640: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
6650: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
6660: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
6670: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
6680: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
6690: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
66a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
66b0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
66c0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
66d0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
66e0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
66f0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
6700: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
6710: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
6720: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
6730: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
6740: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
6750: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
6760: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
6770: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
6780: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
6790: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
67a0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
67b0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
67c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
67d0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
67e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
67f0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
6800: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6810: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
6820: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
6830: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
6840: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
6850: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
6860: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
6870: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
6880: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
6890: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
68a0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
68b0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
68c0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
68d0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
68e0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
68f0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
6900: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
6910: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
6920: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
6930: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
6940: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
6950: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
6960: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
6970: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
6980: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
6990: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
69a0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
69b0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
69c0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
69d0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
69e0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
69f0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6a00: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6a10: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
6a20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6a30: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6a40: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6a50: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
6a60: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
6a70: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
6a80: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
6a90: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
6aa0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
6ab0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
6ac0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
6ad0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
6ae0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
6af0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
6b00: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
6b10: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
6b20: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
6b30: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
6b40: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
6b50: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
6b60: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
6b70: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
6b80: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
6b90: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
6ba0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
6bb0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
6bc0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
6bd0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
6be0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
6bf0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
6c00: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
6c10: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
6c20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6c30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
6c40: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6c50: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
6c60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6c70: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
6c80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6c90: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
6ca0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6cb0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
6cc0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6cd0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
6ce0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6cf0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
6d00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d10: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
6d20: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6d40: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6d50: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6d60: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
6d70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6d80: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
6d90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6da0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6db0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6dc0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6dd0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6de0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6df0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6e00: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6e10: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6e20: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6e30: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6e40: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6e50: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6e60: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6e70: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6e80: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6e90: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6ea0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6eb0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
6ec0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6ed0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6ee0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6ef0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6f00: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6f10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6f20: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6f30: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6f40: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6f50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f60: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6f70: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6f80: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6f90: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6fa0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6fb0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6fc0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
6fd0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
6fe0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
6ff0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
7000: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
7010: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
7020: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
7030: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
7040: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
7050: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
7060: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
7070: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
7080: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
7090: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
70a0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
70b0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
70c0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
70d0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
70e0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
70f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7100: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
7110: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
7120: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7130: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
7140: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
7150: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
7160: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
7170: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
7180: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
7190: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
71a0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
71b0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
71c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
71d0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
71e0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
71f0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
7200: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
7210: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
7220: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
7230: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
7240: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7250: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
7260: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
7270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
7280: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
7290: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
72d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
72e0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
72f0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
7300: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
7310: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
7320: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
7330: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7340: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
7350: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
7360: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
7370: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
7380: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7390: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
73a0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
73b0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
73c0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
73d0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
73e0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
73f0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
7400: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
7410: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
7420: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
7430: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
7440: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
7450: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
7460: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
7470: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7480: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
7490: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
74a0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
74b0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
74c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
74d0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
74e0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
74f0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
7500: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
7510: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7520: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
7530: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
7540: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
7550: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
7560: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
7570: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7580: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
7590: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
75a0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
75b0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
75c0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
75d0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
75e0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
75f0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
7600: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
7610: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
7620: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
7630: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
7640: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
7650: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
7660: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
7670: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7680: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
7690: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
76a0: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
76b0: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
76c0: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
76d0: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
76e0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
76f0: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
7700: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
7710: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
7720: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
7730: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
7740: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
7750: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
7760: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
7770: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
7780: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
7790: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
77a0: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
77b0: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
77c0: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
77d0: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
77e0: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
77f0: 73 74 65 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ster..*/.#define
7800: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7810: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7830: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7840: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
7850: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
7860: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
7870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7880: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
7890: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
78a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
78b0: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 35  ZE_HINT        5
78c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
78d0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
78e0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
78f0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
7900: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
7910: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
7920: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
7930: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
7940: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
7950: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
7960: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
7970: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
7980: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
7990: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
79a0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
79b0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
79c0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
79d0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
79e0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
79f0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
7a00: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
7a10: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
7a20: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
7a30: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
7a40: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
7a50: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7a60: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
7a70: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
7a80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7a90: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7aa0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
7ab0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
7ac0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
7ad0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
7ae0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
7af0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
7b00: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
7b10: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
7b20: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
7b30: 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystem"..**.** Th
7b40: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
7b50: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
7b60: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
7b70: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
7b80: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
7b90: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
7ba0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
7bb0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
7bc0: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
7bd0: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
7be0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
7bf0: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
7c00: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
7c10: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
7c20: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
7c30: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
7c40: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
7c50: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
7c60: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
7c70: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
7c80: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
7c90: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
7ca0: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
7cb0: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
7cc0: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
7cd0: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
7ce0: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
7cf0: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
7d00: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
7d10: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
7d20: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
7d30: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
7d40: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
7d50: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
7d60: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
7d70: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
7d80: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
7d90: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
7da0: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
7db0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
7dc0: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
7dd0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
7de0: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
7df0: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
7e00: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
7e10: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
7e20: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
7e30: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
7e40: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
7e50: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
7e60: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
7e70: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
7e80: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
7e90: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
7ea0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
7eb0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
7ec0: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
7ed0: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
7ee0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
7ef0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7f00: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
7f10: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
7f20: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
7f30: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
7f40: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
7f50: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
7f60: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
7f70: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
7f80: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
7f90: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
7fa0: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
7fb0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
7fc0: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
7fd0: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
7fe0: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
7ff0: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
8000: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
8010: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
8020: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
8030: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
8040: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
8050: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  les..**.** SQLit
8060: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
8070: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
8080: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
8090: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
80a0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
80b0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
80c0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
80d0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20  ullPathname().  
80e0: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
80f0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
8100: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
8110: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
8120: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
8130: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
8140: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
8150: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
8160: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
8170: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
8180: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
8190: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
81a0: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
81b0: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
81c0: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
81d0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
81e0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
81f0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
8200: 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  is xOpen is a NU
8210: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
8220: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
8230: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
8240: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
8250: 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65  the file.  Whene
8260: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
8270: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
8280: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
8290: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
82a0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
82b0: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
82c0: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
82d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
82e0: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
82f0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
8300: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
8310: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
8320: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
8330: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
8340: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
8350: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
8360: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
8370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
8380: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
8390: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
83a0: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
83b0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
83c0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
83d0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
83e0: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
83f0: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
8400: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
8410: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
8420: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
8430: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
8440: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
8450: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
8460: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69   set..**.** SQLi
8470: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
8480: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
8490: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
84a0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
84b0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
84c0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
84d0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
84e0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
84f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8500: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
8510: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
8520: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8530: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8540: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
8550: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
8560: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
8570: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8580: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
8590: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
85a0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
85b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
85c0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
85d0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  URNAL].** </ul>.
85e0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
85f0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
8600: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
8610: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
8620: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
8630: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
8640: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
8650: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
8660: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
8670: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
8680: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
8690: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
86a0: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
86b0: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
86c0: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
86d0: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
86e0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
86f0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
8700: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
8710: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
8720: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
8730: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
8740: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
8750: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
8760: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
8770: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8780: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
8790: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
87a0: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
87b0: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
87c0: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
87d0: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
87e0: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
87f0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
8800: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
8810: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
8820: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
8830: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
8840: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
8850: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
8860: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
8870: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
8880: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
8890: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
88a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
88b0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
88c0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
88d0: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
88e0: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
88f0: 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b  s closed.  The [
8900: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8910: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
8920: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
8930: 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a  MP  databases, j
8940: 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20  ournals and for 
8950: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
8960: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
8970: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
8980: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
8990: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
89a0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
89b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
89c0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
89d0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
89e0: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
89f0: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
8a00: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
8a10: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
8a20: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
8a30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
8a40: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
8a50: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
8a60: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
8a70: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
8a80: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
8a90: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
8aa0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
8ab0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
8ac0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
8ad0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
8ae0: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
8af0: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
8b00: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
8b10: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
8b20: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
8b30: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
8b40: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
8b50: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
8b60: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
8b70: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
8b80: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
8b90: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
8ba0: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
8bb0: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
8bc0: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
8bd0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
8be0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
8bf0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
8c00: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
8c10: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
8c20: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
8c30: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
8c40: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
8c50: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
8c60: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
8c70: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
8c80: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8c90: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
8ca0: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
8cb0: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
8cc0: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
8cd0: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
8ce0: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
8cf0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
8d00: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
8d10: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
8d20: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
8d30: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
8d40: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
8d50: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
8d60: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
8d70: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
8d80: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
8d90: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
8da0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
8db0: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
8dc0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
8dd0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
8de0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
8df0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
8e00: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
8e10: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
8e20: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
8e30: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
8e40: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
8e50: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
8e60: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
8e70: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
8e80: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
8e90: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
8ea0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
8eb0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
8ec0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
8ed0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
8ee0: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
8ef0: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
8f00: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
8f10: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8f20: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
8f30: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
8f40: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
8f50: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
8f60: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
8f70: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
8f80: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
8f90: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
8fa0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
8fb0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
8fc0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
8fd0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
8fe0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8ff0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9000: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9010: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9020: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9030: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9040: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9050: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9060: 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72  eep(), and xCurr
9070: 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66  entTime() interf
9080: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
9090: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
90a0: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
90b0: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
90c0: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
90d0: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
90e0: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
90f0: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
9100: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
9110: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
9120: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
9130: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
9140: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
9150: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
9160: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
9170: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
9180: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
9190: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
91a0: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
91b0: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
91c0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
91d0: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
91e0: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
91f0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
9200: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
9210: 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54 69    The xCurrentTi
9220: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
9230: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
9240: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
9250: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
9260: 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a  and time..**.*/.
9270: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
9280: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
9290: 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73  e3_vfs;.struct s
92a0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
92b0: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
92c0: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
92d0: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
92e0: 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f  ber */.  int szO
92f0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
9300: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
9310: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
9320: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
9330: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
9340: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
9350: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
9360: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
9370: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
9380: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
9390: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
93a0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
93b0: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
93c0: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
93d0: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
93e0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
93f0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
9400: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
9410: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
9420: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
9430: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9440: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
9450: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
9460: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
9470: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
9480: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
9490: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
94a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
94b0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
94c0: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
94d0: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
94e0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
94f0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
9500: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
9510: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
9520: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
9530: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9540: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
9550: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
9560: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
9570: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
9580: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9590: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
95a0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
95b0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
95c0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
95d0: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
95e0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
95f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
9600: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
9610: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
9620: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
9630: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
9640: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
9650: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
9660: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
9670: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
9680: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
9690: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
96a0: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
96b0: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
96c0: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
96d0: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
96e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
96f0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
9700: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
9710: 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20  ar *);.  /* New 
9720: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
9730: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
9740: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
9750: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
9760: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
9770: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
9780: 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a   happens. */.};.
9790: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
97a0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
97b0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
97c0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
97d0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
97e0: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
97f0: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
9800: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
9810: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
9820: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
9830: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
9840: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
9850: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
9860: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
9870: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
9880: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
9890: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
98a0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
98b0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
98c0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
98d0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
98e0: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
98f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9900: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
9910: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
9920: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9930: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
9940: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
9950: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9960: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
9970: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
9980: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
9990: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
99a0: 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  dable..*/.#defin
99b0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
99c0: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
99d0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
99e0: 53 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64  S_READWRITE 1.#d
99f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
9a00: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a  ESS_READ      2.
9a10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9a20: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
9a30: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
9a40: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
9a50: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9a60: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
9a70: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
9a80: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
9a90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9aa0: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
9ab0: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
9ac0: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
9ad0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
9ae0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9af0: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
9b00: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
9b10: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
9b20: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
9b30: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
9b40: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
9b50: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
9b60: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
9b70: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
9b80: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
9b90: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
9ba0: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
9bb0: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
9bc0: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
9bd0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9be0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
9bf0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
9c00: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
9c10: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
9c20: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
9c30: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
9c40: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
9c50: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
9c60: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
9c70: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
9c80: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
9c90: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
9ca0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
9cb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
9cc0: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
9cd0: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
9ce0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9cf0: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
9d00: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
9d10: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
9d20: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
9d30: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
9d40: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
9d50: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
9d60: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
9d70: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
9d80: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
9d90: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9da0: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
9db0: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
9dc0: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
9dd0: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
9de0: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
9df0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
9e00: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
9e10: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
9e20: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
9e30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
9e40: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
9e50: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
9e60: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
9e70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
9e80: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
9e90: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
9ea0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
9eb0: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
9ec0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
9ed0: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
9ee0: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
9ef0: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
9f00: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
9f10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
9f20: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
9f30: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
9f40: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
9f50: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
9f60: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
9f70: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
9f80: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
9f90: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
9fa0: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
9fb0: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
9fc0: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
9fd0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
9fe0: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
9ff0: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
a000: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
a010: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
a020: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
a030: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
a040: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
a050: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a060: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
a070: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
a080: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
a090: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
a0a0: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
a0b0: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
a0c0: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
a0d0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
a0e0: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
a0f0: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
a100: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
a110: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
a120: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
a130: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
a140: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
a150: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a160: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
a170: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
a180: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
a190: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
a1a0: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
a1b0: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
a1c0: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
a1d0: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
a1e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
a1f0: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
a200: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
a210: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
a220: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a230: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
a240: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
a250: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
a260: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
a270: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
a280: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
a290: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
a2a0: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
a2b0: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
a2c0: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
a2d0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
a2e0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
a2f0: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
a300: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
a310: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
a320: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
a330: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a340: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
a350: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
a360: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
a370: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a380: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
a390: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
a3a0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
a3b0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
a3c0: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
a3d0: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
a3e0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
a3f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
a400: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
a410: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a420: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
a430: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
a440: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a450: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
a460: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
a470: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
a480: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
a490: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
a4a0: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
a4b0: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
a4c0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
a4d0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
a4e0: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
a4f0: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
a500: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
a510: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
a520: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
a530: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a540: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
a550: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
a560: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
a570: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
a580: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
a590: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
a5a0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
a5b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
a5c0: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
a5d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a5e0: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
a5f0: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
a600: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
a610: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
a620: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
a630: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
a640: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
a650: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
a660: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
a670: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
a680: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
a690: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
a6a0: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
a6b0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a6c0: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
a6d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
a6e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
a6f0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
a700: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
a710: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
a720: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
a730: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
a740: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
a750: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
a760: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
a770: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a780: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
a790: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
a7a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
a7b0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
a7c0: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
a7d0: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
a7e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
a7f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
a800: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
a810: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
a820: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
a830: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
a840: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
a850: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
a860: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a870: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
a880: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
a890: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
a8a0: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
a8b0: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
a8c0: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
a8d0: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
a8e0: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
a8f0: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
a900: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
a910: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
a920: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
a930: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
a940: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
a950: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
a960: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
a970: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
a980: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
a990: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
a9a0: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
a9b0: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
a9c0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
a9d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a9e0: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
a9f0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
aa00: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
aa10: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
aa20: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
aa30: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
aa40: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
aa50: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
aa60: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
aa70: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
aa80: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
aa90: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
aaa0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
aab0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
aac0: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
aad0: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
aae0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
aaf0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
ab00: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
ab10: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
ab20: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
ab30: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
ab40: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
ab50: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
ab60: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
ab70: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
ab80: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
ab90: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
aba0: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
abb0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
abc0: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
abd0: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
abe0: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
abf0: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
ac00: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
ac10: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
ac20: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
ac30: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ac40: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ac50: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
ac60: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
ac70: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
ac80: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
ac90: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
aca0: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
acb0: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
acc0: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
acd0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
ace0: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
acf0: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
ad00: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
ad10: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
ad20: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
ad30: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
ad40: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
ad50: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
ad60: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
ad70: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
ad80: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
ad90: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
ada0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
adb0: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
adc0: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
add0: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
ade0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
adf0: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
ae00: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
ae10: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
ae20: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
ae30: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
ae40: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
ae50: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
ae60: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
ae70: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
ae80: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
ae90: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
aea0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
aeb0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
aec0: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
aed0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
aee0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
aef0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
af00: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
af10: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
af20: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
af30: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
af40: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
af50: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
af60: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
af70: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
af80: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
af90: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
afa0: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
afb0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
afc0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
afd0: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
afe0: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
aff0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b000: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
b010: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
b020: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
b030: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
b040: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
b050: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
b060: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
b070: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
b080: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
b090: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
b0a0: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
b0b0: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
b0c0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
b0d0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
b0e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b0f0: 69 6f 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45  ions.** EXPERIME
b100: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
b110: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b120: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
b130: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
b140: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
b150: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
b160: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
b170: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
b180: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
b190: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
b1a0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
b1b0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
b1c0: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
b1d0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
b1e0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
b1f0: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
b200: 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a  argument).  The.
b210: 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  ** sqlite3_db_co
b220: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
b230: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20   should only be 
b240: 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  used immediately
b250: 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61   after.** the da
b260: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
b270: 6e 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  n is created usi
b280: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
b290: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
b2a0: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b  _open16()], or [
b2b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
b2c0: 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  )].  .**.** The 
b2d0: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
b2e0: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
b2f0: 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
b300: 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  s the.** configu
b310: 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e  ration verb - an
b320: 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
b330: 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
b340: 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74  t.** aspect of t
b350: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
b360: 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
b370: 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
b380: 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65   The only choice
b390: 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20   for this value 
b3a0: 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  is [SQLITE_DBCON
b3b0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a  FIG_LOOKASIDE]..
b3c0: 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61 72 65  ** New verbs are
b3d0: 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64   likely to be ad
b3e0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
b3f0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
b400: 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
b410: 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64  arguments depend
b420: 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a   on the verb..**
b430: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
b440: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
b450: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
b460: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
b470: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
b480: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
b490: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  essful..*/.SQLIT
b4a0: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
b4b0: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
b4c0: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
b4d0: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
b4e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
b4f0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
b500: 52 6f 75 74 69 6e 65 73 0a 2a 2a 20 45 58 50 45  Routines.** EXPE
b510: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41  RIMENTAL.**.** A
b520: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b530: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
b540: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
b550: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
b560: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
b570: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b580: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
b590: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
b5a0: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
b5b0: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
b5c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b5d0: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
b5e0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
b5f0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
b600: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
b610: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
b620: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
b630: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
b640: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
b650: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
b660: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
b670: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
b680: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
b690: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
b6a0: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
b6b0: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
b6c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
b6d0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
b6e0: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
b6f0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
b700: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b710: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
b720: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
b730: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b740: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
b750: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
b760: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
b770: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
b780: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
b790: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
b7a0: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
b7b0: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
b7c0: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
b7d0: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
b7e0: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
b7f0: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
b800: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
b810: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
b820: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
b830: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
b840: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
b850: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
b860: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
b870: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
b880: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
b890: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
b8a0: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
b8b0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b8c0: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
b8d0: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
b8e0: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
b8f0: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
b900: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
b910: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
b920: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
b930: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
b940: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
b950: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
b960: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
b970: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
b980: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
b990: 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  oc and xFree met
b9a0: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
b9b0: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
b9c0: 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
b9d0: 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
b9e0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
b9f0: 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65  rary..** The xRe
ba00: 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73  alloc method mus
ba10: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c  t work like real
ba20: 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73  loc() from the s
ba30: 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
ba40: 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78  y.** with the ex
ba50: 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20  ception that if 
ba60: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
ba70: 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20  ent to xRealloc 
ba80: 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61  is zero,.** xRea
ba90: 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e  lloc must be a n
baa0: 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e  o-op - it must n
bab0: 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61  ot perform any a
bac0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20  llocation or.** 
bad0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e  deallocation.  ^
bae0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
baf0: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
bb00: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
bb10: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
bb20: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
bb30: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
bb40: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
bb50: 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63  ..** And so in c
bb60: 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e  ases where xRoun
bb70: 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75 72  dup always retur
bb80: 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75  ns a positive nu
bb90: 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f  mber,.** xReallo
bba0: 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78  c can perform ex
bbb0: 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74 61  actly as the sta
bbc0: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72 65  ndard library re
bbd0: 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73  alloc() and.** s
bbe0: 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c  till be in compl
bbf0: 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73 20  iance with this 
bc00: 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a  specification..*
bc10: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
bc20: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
bc30: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
bc40: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bc50: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
bc60: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
bc70: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
bc80: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
bc90: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
bca0: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
bcb0: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
bcc0: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
bcd0: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
bce0: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
bcf0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
bd00: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
bd10: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
bd20: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
bd30: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
bd40: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
bd50: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
bd60: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
bd70: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
bd80: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
bd90: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
bda0: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
bdb0: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
bdc0: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
bdd0: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
bde0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
bdf0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
be00: 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
be10: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
be20: 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
be30: 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
be40: 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
be50: 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
be60: 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
be70: 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
be80: 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
be90: 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
bea0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
beb0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
bec0: 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
bed0: 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
bee0: 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
bef0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bf00: 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70  tor.  (For examp
bf10: 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20  le,.** it might 
bf20: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71  allocate any req
bf30: 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20  uire mutexes or 
bf40: 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72  initialize inter
bf50: 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75  nal data.** stru
bf60: 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68  ctures.  The xSh
bf70: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
bf80: 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65   invoked (indire
bf90: 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c  ctly) by.** [sql
bfa0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
bfb0: 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c   and should deal
bfc0: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75  locate any resou
bfd0: 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a  rces acquired.**
bfe0: 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20   by xInit.  The 
bff0: 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72  pAppData pointer
c000: 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
c010: 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
c020: 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78  o.** xInit and x
c030: 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20  Shutdown..**.** 
c040: 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65  SQLite holds the
c050: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
c060: 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75  TATIC_MASTER] mu
c070: 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f  tex when it invo
c080: 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74  kes.** the xInit
c090: 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20   method, so the 
c0a0: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65  xInit method nee
c0b0: 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73  d not be threads
c0c0: 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68  afe.  The.** xSh
c0d0: 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73  utdown method is
c0e0: 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f   only called fro
c0f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  m [sqlite3_shutd
c100: 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65  own()] so it doe
c110: 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f  s.** not need to
c120: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65   be threadsafe e
c130: 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20  ither.  For all 
c140: 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53  other methods, S
c150: 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74  QLite.** holds t
c160: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
c170: 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74  _STATIC_MEM] mut
c180: 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ex as long as th
c190: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
c1a0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63  FIG_MEMSTATUS] c
c1b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c1c0: 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e  ion is turned on
c1d0: 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73   (which.** it is
c1e0: 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64   by default) and
c1f0: 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20   so the methods 
c200: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
c210: 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a  y serialized..**
c220: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51   However, if [SQ
c230: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
c240: 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c  TATUS] is disabl
c250: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68  ed, then the oth
c260: 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75  er.** methods mu
c270: 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
c280: 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68   or else make th
c290: 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d  eir own arrangem
c2a0: 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69  ents for.** seri
c2b0: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  alization..**.**
c2c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76   SQLite will nev
c2d0: 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28  er invoke xInit(
c2e0: 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  ) more than once
c2f0: 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65   without an inte
c300: 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20  rvening.** call 
c310: 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a  to xShutdown()..
c320: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c330: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
c340: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
c350: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
c360: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
c370: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
c380: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
c390: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
c3a0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
c3b0: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
c3c0: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
c3d0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
c3e0: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
c3f0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
c400: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
c410: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
c420: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
c430: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
c440: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
c450: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
c460: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
c470: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
c480: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
c490: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
c4a0: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
c4b0: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
c4c0: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
c4d0: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
c4e0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
c4f0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
c500: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
c510: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
c520: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
c530: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
c540: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
c550: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
c560: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
c570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
c580: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
c590: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
c5a0: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
c5b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
c5c0: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
c5d0: 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  s.** EXPERIMENTA
c5e0: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  L.**.** These co
c5f0: 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
c600: 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
c610: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
c620: 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
c630: 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
c640: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
c650: 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
c660: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
c670: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
c680: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
c690: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
c6a0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
c6b0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
c6c0: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
c6d0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
c6e0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
c6f0: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
c700: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
c710: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
c720: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
c730: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c740: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
c750: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
c760: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
c770: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
c780: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
c790: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
c7a0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
c7b0: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
c7c0: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
c7d0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
c7e0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
c7f0: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
c800: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
c810: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
c820: 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
c830: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
c840: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
c850: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
c860: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
c870: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
c880: 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
c890: 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
c8a0: 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
c8b0: 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
c8c0: 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
c8d0: 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
c8e0: 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
c8f0: 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
c900: 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
c910: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
c920: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
c930: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
c940: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
c950: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
c960: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
c970: 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
c980: 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
c990: 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
c9a0: 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
c9b0: 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
c9c0: 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
c9d0: 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
c9e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
c9f0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
ca00: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
ca10: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
ca20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ca30: 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
ca40: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ca50: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
ca60: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
ca70: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
ca80: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
ca90: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
caa0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
cab0: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
cac0: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
cad0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
cae0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
caf0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
cb00: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
cb10: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
cb20: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
cb30: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
cb40: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
cb50: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
cb60: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
cb70: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
cb80: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
cb90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
cba0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
cbb0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
cbc0: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
cbd0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
cbe0: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
cbf0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
cc00: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
cc10: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
cc20: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
cc30: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
cc40: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
cc50: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
cc60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
cc70: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
cc80: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
cc90: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
cca0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
ccb0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
ccc0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
ccd0: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
cce0: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
ccf0: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
cd00: 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
cd10: 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
cd20: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
cd30: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
cd40: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
cd50: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
cd60: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
cd70: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
cd80: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
cd90: 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
cda0: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
cdb0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
cdc0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
cdd0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
cde0: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
cdf0: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
ce00: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
ce10: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
ce20: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
ce30: 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
ce40: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
ce50: 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
ce60: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
ce70: 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
ce80: 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
ce90: 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
cea0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
ceb0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
cec0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
ced0: 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
cee0: 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
cef0: 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
cf00: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
cf10: 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
cf20: 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
cf30: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
cf40: 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
cf50: 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
cf60: 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
cf70: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
cf80: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
cf90: 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
cfa0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
cfb0: 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
cfc0: 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
cfd0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
cfe0: 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
cff0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
d000: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
d010: 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
d020: 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
d030: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
d040: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
d050: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
d060: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
d070: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
d080: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
d090: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
d0a0: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
d0b0: 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
d0c0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
d0d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
d0e0: 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
d0f0: 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
d100: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
d110: 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
d120: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
d130: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d140: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
d150: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d160: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
d170: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
d180: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
d190: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
d1a0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
d1b0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
d1c0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
d1d0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
d1e0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
d1f0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
d200: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
d210: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
d220: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d230: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
d240: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
d250: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
d260: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
d270: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
d280: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
d290: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
d2a0: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
d2b0: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
d2c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
d2d0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
d2e0: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
d2f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d300: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
d310: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d320: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d330: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
d340: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
d350: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
d360: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
d370: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
d380: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
d390: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
d3a0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
d3b0: 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c  cture.  The [sql
d3c0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
d3d0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
d3e0: 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
d3f0: 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
d400: 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
d410: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
d420: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
d430: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
d440: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
d450: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
d460: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
d470: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
d480: 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
d490: 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
d4a0: 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
d4b0: 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
d4c0: 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
d4d0: 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
d4e0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
d4f0: 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
d500: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
d510: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
d520: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
d530: 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70  type int, interp
d540: 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62  reted as a .** b
d550: 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
d560: 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
d570: 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
d580: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
d590: 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73  ation .** statis
d5a0: 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
d5b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
d5c0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
d5d0: 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20  sabled, the .** 
d5e0: 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
d5f0: 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
d600: 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
d610: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
d620: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
d630: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
d640: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
d650: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
d660: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
d670: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
d680: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
d690: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
d6a0: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
d6b0: 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
d6c0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
d6d0: 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
d6e0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
d6f0: 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
d700: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
d710: 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
d720: 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
d730: 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
d740: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
d750: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
d760: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
d770: 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
d780: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d790: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
d7a0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
d7b0: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
d7c0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
d7d0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
d7e0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
d7f0: 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
d800: 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
d810: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
d820: 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
d830: 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
d840: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
d850: 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
d860: 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ach allocations 
d870: 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
d880: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
d890: 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
d8a0: 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
d8b0: 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
d8c0: 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
d8d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
d8e0: 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
d8f0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
d900: 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20  multiple of 16. 
d910: 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  The sz parameter
d920: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77   should be a few
d930: 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72   bytes.** larger
d940: 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c   than the actual
d950: 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72   scratch space r
d960: 65 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69  equired due to i
d970: 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64  nternal overhead
d980: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
d990: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
d9a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
d9b0: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
d9c0: 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
d9d0: 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
d9e0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
d9f0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
da00: 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  o more than one 
da10: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 70  scratch buffer p
da20: 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
da30: 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
da40: 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65  t to the expecte
da50: 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
da60: 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53   of threads.  ^S
da70: 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65  QLite will.** ne
da80: 76 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63  ver require a sc
da90: 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
daa0: 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
dab0: 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
dac0: 61 73 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65  ase.** page size
dad0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  . ^If SQLite nee
dae0: 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
daf0: 6e 61 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  nal scratch memo
db00: 72 79 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68  ry beyond .** wh
db10: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
db20: 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61  y this configura
db30: 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65  tion option, the
db40: 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  n .** [sqlite3_m
db50: 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65  alloc()] will be
db60: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
db70: 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65  the memory neede
db80: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
db90: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
dba0: 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
dbb0: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
dbc0: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
dbd0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
dbe0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
dbf0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
dc00: 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
dc10: 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
dc20: 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
dc30: 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f  che implemenatio
dc40: 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
dc50: 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
dc60: 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
dc70: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
dc80: 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
dc90: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
dca0: 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
dcb0: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
dcc0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74  ONFIG_PCACHE opt
dcd0: 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
dce0: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
dcf0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
dd00: 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
dd10: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
dd20: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
dd30: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
dd40: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
dd50: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
dd60: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
dd70: 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
dd80: 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
dd90: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
dda0: 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
ddb0: 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
ddc0: 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
ddd0: 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
dde0: 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
ddf0: 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
de00: 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
de10: 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
de20: 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
de30: 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
de40: 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
de50: 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
de60: 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
de70: 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
de80: 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
de90: 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
dea0: 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
deb0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
dec0: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
ded0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
dee0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
def0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
df00: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
df10: 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
df20: 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
df30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
df40: 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
df50: 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
df60: 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
df70: 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
df80: 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
df90: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
dfa0: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
dfb0: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
dfc0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
dfd0: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
dfe0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
dff0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
e000: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
e010: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
e020: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65  e space..** ^The
e030: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e040: 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72  might use one or
e050: 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62   more of the N b
e060: 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a  uffers to hold .
e070: 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e  ** memory accoun
e080: 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ting information
e090: 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  . The pointer in
e0a0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e0b0: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
e0c0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
e0d0: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
e0e0: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
e0f0: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
e100: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
e110: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
e120: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e130: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
e140: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
e150: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
e160: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
e170: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
e180: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
e190: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
e1a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
e1b0: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
e1c0: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
e1d0: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
e1e0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
e1f0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
e200: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
e210: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
e220: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
e230: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
e240: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
e250: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
e260: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
e270: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
e280: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
e290: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
e2a0: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
e2b0: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
e2c0: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
e2d0: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
e2e0: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
e2f0: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
e300: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
e310: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
e320: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
e330: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
e340: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
e350: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
e360: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e370: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
e380: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
e390: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
e3a0: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
e3b0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
e3c0: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
e3d0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
e3e0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
e3f0: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
e400: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
e410: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
e420: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
e430: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
e440: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
e450: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
e460: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
e470: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
e480: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
e490: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
e4a0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
e4b0: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
e4c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
e4d0: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
e4e0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e4f0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
e500: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
e510: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
e520: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
e530: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
e540: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
e550: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
e560: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
e570: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
e580: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
e590: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
e5a0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
e5b0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
e5c0: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
e5d0: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
e5e0: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
e5f0: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
e600: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
e610: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
e620: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
e630: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
e640: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
e650: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
e660: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
e670: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
e680: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
e690: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
e6a0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
e6b0: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
e6c0: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
e6d0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
e6e0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
e6f0: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
e700: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
e710: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
e720: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
e730: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
e740: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
e750: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e760: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
e770: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
e780: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
e790: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
e7a0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e7b0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
e7c0: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
e7d0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
e7e0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
e7f0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
e800: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
e810: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
e820: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
e830: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e840: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
e850: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
e860: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
e870: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
e880: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
e890: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
e8a0: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
e8b0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
e8c0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
e8d0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
e8e0: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
e8f0: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
e900: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
e910: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
e920: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
e930: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
e940: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
e950: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
e960: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
e970: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
e980: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
e990: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
e9a0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
e9b0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
e9c0: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
e9d0: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
e9e0: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
e9f0: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
ea00: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
ea10: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ea20: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
ea30: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
ea40: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
ea50: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
ea60: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
ea70: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
ea80: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
ea90: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
eaa0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
eab0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
eac0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
ead0: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
eae0: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
eaf0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
eb00: 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
eb10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
eb20: 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
eb30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
eb40: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
eb50: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
eb60: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
eb70: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
eb80: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
eb90: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
eba0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
ebb0: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
ebc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ebd0: 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
ebe0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
ebf0: 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
ec00: 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
ec10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
ec20: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
ec30: 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
ec40: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
ec50: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
ec60: 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
ec70: 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
ec80: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
ec90: 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
eca0: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
ecb0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ecc0: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
ecd0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
ece0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
ecf0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
ed00: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
ed10: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
ed20: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
ed30: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
ed40: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
ed50: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
ed60: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
ed70: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
ed80: 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
ed90: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
eda0: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
edb0: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
edc0: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
edd0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
ede0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
edf0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
ee00: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
ee10: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
ee20: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ee30: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
ee40: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ee50: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
ee60: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
ee70: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
ee80: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
ee90: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
eea0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
eeb0: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
eec0: 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
eed0: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
eee0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
eef0: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
ef00: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
ef10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
ef20: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
ef30: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
ef40: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
ef50: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
ef60: 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
ef70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ef80: 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
ef90: 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
efa0: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
efb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
efc0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
efd0: 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
efe0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
eff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f000: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
f010: 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
f020: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
f030: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f040: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
f050: 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
f060: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
f070: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
f080: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
f090: 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
f0a0: 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
f0b0: 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
f0c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f0d0: 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
f0e0: 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
f0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f100: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
f110: 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
f120: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f130: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
f140: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
f150: 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
f160: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
f170: 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
f180: 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
f190: 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
f1a0: 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
f1b0: 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
f1c0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f1d0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
f1e0: 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
f1f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f200: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
f210: 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74      14  /* sqlit
f220: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
f230: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
f240: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
f250: 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
f260: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
f270: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
f280: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f290: 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
f2a0: 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
f2b0: 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  * */../*.** CAPI
f2c0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
f2d0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 45  ion Options.** E
f2e0: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
f2f0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
f300: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
f310: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
f320: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f330: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
f340: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
f350: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f360: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
f370: 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
f380: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
f390: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f3a0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
f3b0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
f3c0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
f3d0: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
f3e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f3f0: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
f400: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
f410: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
f420: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
f430: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
f440: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f450: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
f460: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
f470: 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
f480: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f490: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
f4a0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
f4b0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
f4c0: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
f4d0: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
f4e0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
f4f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
f500: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
f510: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
f520: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
f530: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
f540: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
f550: 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
f560: 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
f570: 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
f580: 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
f590: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
f5a0: 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
f5b0: 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
f5c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f5d0: 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
f5e0: 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
f5f0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
f600: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
f610: 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
f620: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d   pointer to an m
f630: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
f640: 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
f650: 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
f660: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f670: 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
f680: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
f690: 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
f6a0: 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
f6b0: 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
f6c0: 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
f6d0: 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
f6e0: 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
f6f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
f700: 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
f710: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
f720: 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
f730: 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
f740: 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
f750: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
f760: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
f770: 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
f780: 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
f790: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
f7a0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
f7b0: 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
f7c0: 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
f7d0: 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
f7e0: 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
f7f0: 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
f800: 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
f810: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
f820: 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
f830: 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
f840: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
f850: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
f860: 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
f870: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
f880: 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
f890: 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
f8a0: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
f8b0: 6c 6c 65 72 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  ller.** multiple
f8c0: 20 6f 66 20 38 2e 20 20 53 65 65 20 61 6c 73 6f   of 8.  See also
f8d0: 3a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  : [SQLITE_CONFIG
f8e0: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 3c 2f 64 64 3e  _LOOKASIDE]</dd>
f8f0: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
f900: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
f910: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
f920: 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
f930: 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
f940: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f950: 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
f960: 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
f970: 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
f980: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
f990: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
f9a0: 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
f9b0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
f9c0: 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
f9d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
f9e0: 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
f9f0: 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
fa00: 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
fa10: 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
fa20: 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
fa30: 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
fa40: 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
fa50: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
fa60: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
fa70: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
fa80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fa90: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
faa0: 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
fab0: 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
fac0: 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
fad0: 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
fae0: 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
faf0: 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
fb00: 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
fb10: 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
fb20: 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
fb30: 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
fb40: 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
fb50: 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
fb60: 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
fb70: 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
fb80: 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
fb90: 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
fba0: 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
fbb0: 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
fbc0: 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
fbd0: 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
fbe0: 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
fbf0: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
fc00: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
fc10: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
fc20: 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
fc30: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
fc40: 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
fc50: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
fc60: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
fc70: 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
fc80: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
fc90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fca0: 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
fcb0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
fcc0: 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73    ^If no success
fcd0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
fce0: 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
fcf0: 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
fd00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
fd10: 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
fd20: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
fd30: 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
fd40: 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
fd50: 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77  r, then the [row
fd60: 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
fd70: 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
fd80: 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
fd90: 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
fda0: 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
fdb0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
fdc0: 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
fdd0: 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
fde0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
fdf0: 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
fe00: 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
fe10: 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
fe20: 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
fe30: 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
fe40: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
fe50: 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
fe60: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
fe70: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
fe80: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
fe90: 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
fea0: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
feb0: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
fec0: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
fed0: 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
fee0: 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
fef0: 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
ff00: 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
ff10: 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
ff20: 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
ff30: 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
ff40: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
ff50: 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
ff60: 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
ff70: 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
ff80: 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
ff90: 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
ffa0: 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
ffb0: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
ffc0: 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
ffd0: 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
ffe0: 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
fff0: 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
10000 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
10010 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
10020 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
10030 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
10040 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
10050 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
10060 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
10070 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
10080 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
10090 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
100a0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
100b0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
100c0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
100d0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
100e0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
100f0 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
10100 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
10110 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
10120 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
10130 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
10140 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
10150 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
10160 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
10170 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
10180 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
10190 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
101a0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
101b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
101c0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
101d0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
101e0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
101f0 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
10200 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
10210 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
10220 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
10230 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
10240 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
10250 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
10260 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
10270 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
10280 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
10290 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
102a0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
102b0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
102c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
102d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
102e0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
102f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10300 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
10310 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
10320 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
10330 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10340 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
10350 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
10360 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
10370 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
10380 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
10390 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
103a0 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
103b0 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
103c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
103d0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
103e0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
103f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
10400 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
10410 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
10420 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
10430 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
10440 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
10450 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
10460 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
10470 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
10480 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
10490 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
104a0 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
104b0 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
104c0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
104d0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
104e0 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
104f0 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
10500 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
10510 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
10520 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
10530 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
10540 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
10550 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
10560 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
10570 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
10580 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
10590 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
105a0 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
105b0 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
105c0 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
105d0 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
105e0 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
105f0 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
10600 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
10610 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
10620 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
10630 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
10640 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
10650 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
10660 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
10670 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
10680 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
10690 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
106a0 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
106b0 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
106c0 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
106d0 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
106e0 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
106f0 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
10700 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
10710 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
10720 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
10730 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
10740 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
10750 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
10760 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
10770 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
10780 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
10790 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
107a0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
107b0 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
107c0 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
107d0 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
107e0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
107f0 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
10800 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
10810 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
10820 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
10830 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
10840 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
10850 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
10860 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
10870 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
10880 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
10890 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
108a0 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
108b0 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
108c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
108d0 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
108e0 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
108f0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
10900 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
10910 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
10920 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
10930 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
10940 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
10950 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
10960 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
10970 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
10980 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
10990 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
109a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
109b0 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
109c0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
109d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
109e0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
109f0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
10a00 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
10a10 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
10a20 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
10a30 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
10a40 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
10a50 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
10a60 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
10a70 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
10a80 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
10a90 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
10aa0 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
10ab0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
10ac0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
10ad0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
10ae0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
10af0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
10b00 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
10b10 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
10b20 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
10b30 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
10b40 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
10b50 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
10b60 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
10b70 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
10b80 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
10b90 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
10ba0 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
10bb0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
10bc0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10bd0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
10be0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
10bf0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
10c00 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
10c10 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
10c20 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
10c30 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
10c40 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
10c50 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
10c60 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
10c70 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
10c80 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
10c90 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
10ca0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
10cb0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
10cc0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
10cd0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
10ce0 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
10cf0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
10d00 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
10d10 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
10d20 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
10d30 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
10d40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
10d50 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
10d60 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
10d70 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
10d80 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
10d90 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
10da0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10db0 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
10dc0 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
10dd0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
10de0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
10df0 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
10e00 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
10e10 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
10e20 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
10e30 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
10e40 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
10e50 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
10e60 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
10e70 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
10e80 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
10e90 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
10ea0 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
10eb0 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
10ec0 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
10ed0 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
10ee0 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
10ef0 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
10f00 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
10f10 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
10f20 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
10f30 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
10f40 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
10f50 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
10f60 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
10f70 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
10f80 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
10f90 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
10fa0 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
10fb0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
10fc0 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
10fd0 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
10fe0 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
10ff0 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
11000 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
11010 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
11020 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
11030 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
11040 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
11050 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
11060 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
11070 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
11080 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
11090 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
110a0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
110b0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
110c0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
110d0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
110e0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
110f0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
11100 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
11110 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
11120 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
11130 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
11140 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
11150 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
11160 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
11170 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
11180 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
11190 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
111a0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
111b0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
111c0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
111d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
111e0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
111f0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
11200 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
11210 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
11220 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
11230 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
11240 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
11250 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
11260 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
11270 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
11280 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
11290 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
112a0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
112b0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
112c0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
112d0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
112e0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
112f0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
11300 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
11310 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
11320 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
11330 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
11340 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
11350 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
11360 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
11370 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
11380 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
11390 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
113a0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
113b0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
113c0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
113d0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
113e0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
113f0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
11400 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
11410 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
11420 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
11430 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
11440 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
11450 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
11460 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
11470 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
11480 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
11490 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
114a0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
114b0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
114c0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
114d0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
114e0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
114f0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
11500 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
11510 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
11520 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11530 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
11540 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
11550 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
11560 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
11570 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
11580 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
11590 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
115a0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
115b0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
115c0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
115d0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
115e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
115f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
11600 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
11610 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
11620 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
11630 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
11640 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
11650 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11660 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
11670 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
11680 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
11690 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
116a0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
116b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
116c0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
116d0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
116e0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
116f0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
11700 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
11710 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
11720 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
11730 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
11740 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
11750 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
11760 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
11770 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
11780 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
11790 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
117a0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
117b0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
117c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
117d0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
117e0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
117f0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
11800 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
11810 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
11820 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
11830 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
11840 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
11850 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
11860 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
11870 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
11880 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11890 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
118a0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
118b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
118c0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
118d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
118e0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
118f0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
11900 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
11910 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
11920 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
11930 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
11940 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
11950 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
11960 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
11970 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
11980 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
11990 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
119a0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
119b0 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
119c0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
119d0 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
119e0 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
119f0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
11a00 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
11a10 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
11a20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
11a30 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
11a40 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
11a50 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
11a60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
11a70 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
11a80 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
11a90 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
11aa0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
11ab0 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
11ac0 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
11ad0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
11ae0 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
11af0 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
11b00 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
11b10 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
11b20 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
11b30 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
11b40 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
11b50 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
11b60 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
11b70 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
11b80 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
11b90 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
11ba0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
11bb0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
11bc0 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
11bd0 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
11be0 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
11bf0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
11c00 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
11c10 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
11c20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
11c30 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
11c40 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
11c50 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
11c60 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
11c70 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
11c80 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
11c90 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
11ca0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
11cb0 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
11cc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11cd0 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
11ce0 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
11cf0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
11d00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
11d10 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
11d20 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
11d30 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
11d40 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
11d50 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
11d60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
11d70 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
11d80 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
11d90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
11da0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
11db0 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
11dc0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
11dd0 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
11de0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
11df0 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
11e00 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
11e10 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
11e20 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
11e30 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
11e40 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
11e50 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
11e60 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
11e70 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
11e80 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
11e90 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
11ea0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
11eb0 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
11ec0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
11ed0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
11ee0 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
11ef0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
11f00 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
11f10 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
11f20 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
11f30 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
11f40 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
11f50 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
11f60 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
11f70 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
11f80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
11f90 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
11fa0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
11fb0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
11fc0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
11fd0 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
11fe0 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
11ff0 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
12000 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
12010 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
12020 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
12030 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
12040 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
12050 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
12060 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
12070 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
12080 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
12090 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
120a0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
120b0 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
120c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
120d0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
120e0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
120f0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
12100 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12110 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
12120 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
12130 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
12140 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
12150 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
12160 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
12170 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
12180 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
12190 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
121a0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
121b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
121c0 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
121d0 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
121e0 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
121f0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
12200 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
12210 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
12220 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
12230 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
12240 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
12250 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
12260 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
12270 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
12280 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
12290 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
122a0 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
122b0 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
122c0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
122d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
122e0 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
122f0 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
12300 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
12310 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
12320 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
12330 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
12340 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
12350 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
12360 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
12370 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
12380 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
12390 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
123a0 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
123b0 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
123c0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
123d0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
123e0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
123f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
12400 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
12410 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
12420 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
12430 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
12440 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
12450 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
12460 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
12470 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
12480 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
12490 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
124a0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
124b0 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
124c0 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
124d0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
124e0 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
124f0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
12500 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
12510 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
12520 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
12530 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
12540 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
12550 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
12560 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
12570 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
12580 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
12590 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
125a0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
125b0 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
125c0 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
125d0 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
125e0 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
125f0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
12600 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
12610 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
12620 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
12630 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
12640 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
12650 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
12660 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
12670 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
12680 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
12690 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
126a0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
126b0 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
126c0 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
126d0 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
126e0 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
126f0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
12700 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
12710 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
12720 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
12730 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
12740 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
12750 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
12760 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
12770 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
12780 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
12790 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
127a0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
127b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
127c0 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
127d0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
127e0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
127f0 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
12800 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
12810 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
12820 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
12830 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
12840 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
12850 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
12860 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
12870 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
12880 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
12890 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
128a0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
128b0 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
128c0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
128d0 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
128e0 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
128f0 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
12900 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
12910 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
12920 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
12930 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
12940 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
12950 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
12960 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
12970 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
12980 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
12990 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
129a0 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
129b0 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
129c0 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
129d0 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
129e0 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
129f0 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
12a00 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
12a10 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
12a20 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
12a30 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
12a40 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
12a50 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
12a60 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
12a70 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
12a80 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
12a90 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
12aa0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
12ab0 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
12ac0 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
12ad0 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
12ae0 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
12af0 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
12b00 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
12b10 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
12b20 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
12b30 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
12b40 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
12b50 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
12b60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
12b70 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
12b80 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
12b90 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
12ba0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
12bb0 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
12bc0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
12bd0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
12be0 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
12bf0 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
12c00 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
12c10 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
12c20 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
12c30 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
12c40 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
12c50 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
12c60 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
12c70 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
12c80 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
12c90 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
12ca0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
12cb0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
12cc0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
12cd0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
12ce0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
12cf0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
12d00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12d10 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
12d20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
12d30 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
12d40 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
12d50 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
12d60 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
12d70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
12d80 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
12d90 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
12da0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
12db0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
12dc0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
12dd0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
12de0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
12df0 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
12e00 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
12e10 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
12e20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
12e30 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
12e40 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
12e50 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
12e60 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
12e70 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
12e80 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
12e90 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
12ea0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
12eb0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
12ec0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
12ed0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
12ee0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
12ef0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
12f00 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
12f10 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12f20 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
12f30 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
12f40 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
12f50 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
12f60 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
12f70 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
12f80 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
12f90 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
12fa0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
12fb0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
12fc0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
12fd0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
12fe0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
12ff0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
13000 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
13010 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
13020 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
13030 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
13040 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
13050 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
13060 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
13070 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
13080 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
13090 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
130a0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
130b0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
130c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
130d0 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
130e0 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
130f0 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
13100 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
13110 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
13120 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
13130 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
13140 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
13150 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13160 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
13170 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
13180 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
13190 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
131a0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
131b0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
131c0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
131d0 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
131e0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
131f0 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
13200 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
13210 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
13220 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
13230 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
13240 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
13250 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
13260 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
13270 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
13280 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
13290 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
132a0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
132b0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
132c0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
132d0 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
132e0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
132f0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
13300 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
13310 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
13320 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
13330 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
13340 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
13350 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
13360 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
13370 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
13380 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
13390 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
133a0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
133b0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
133c0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
133d0 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
133e0 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
133f0 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
13400 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
13410 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
13420 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
13430 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
13440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
13450 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
13460 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
13470 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
13480 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
13490 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
134a0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
134b0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
134c0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
134d0 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
134e0 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
134f0 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
13500 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
13510 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
13520 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
13530 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65  ** As an example
13540 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
13550 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
13560 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
13570 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
13580 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
13590 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
135a0 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
135b0 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
135c0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
135d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
135e0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
135f0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
13600 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
13610 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
13620 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
13630 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13640 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
13650 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
13660 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
13670 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
13680 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
13690 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
136a0 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
136b0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
136c0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
136d0 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
136e0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
136f0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
13700 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
13710 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
13720 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
13730 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
13740 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
13750 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
13760 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
13770 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
13780 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
13790 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
137a0 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
137b0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
137c0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
137d0 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
137e0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
137f0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
13800 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
13810 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
13820 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13830 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
13840 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13850 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ote>.**.** ^The 
13860 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
13870 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
13880 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
13890 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
138a0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
138b0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
138c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
138d0 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
138e0 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
138f0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
13900 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
13910 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
13920 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
13930 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
13940 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
13950 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
13960 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
13970 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
13980 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
13990 0a 2a 2a 20 69 74 20 73 68 6f 75 6c 64 20 70 61  .** it should pa
139a0 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
139b0 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
139c0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
139d0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
139e0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
139f0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
13a00 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
13a10 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
13a20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
13a30 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
13a40 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
13a50 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
13a60 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
13a70 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
13a80 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
13a90 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
13aa0 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
13ab0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
13ac0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
13ad0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
13ae0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
13af0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  fely..**.** ^(Th
13b00 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
13b10 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
13b20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
13b30 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
13b40 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
13b50 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
13b60 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
13b70 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
13b80 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
13b90 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
13ba0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
13bb0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
13bc0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
13bd0 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
13be0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
13bf0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
13c00 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
13c10 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
13c20 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
13c30 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
13c40 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
13c50 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
13c60 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
13c70 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
13c80 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
13c90 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
13ca0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
13cb0 28 29 5d 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71  ()].)^.*/.int sq
13cc0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
13cd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
13ce0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
13cf0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
13d00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
13d10 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
13d20 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
13d30 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
13d40 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
13d50 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
13d60 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
13d70 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
13d80 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
13d90 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
13da0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
13db0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
13dc0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
13dd0 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
13de0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
13df0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
13e00 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
13e10 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
13e20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
13e30 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
13e40 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
13e50 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
13e60 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
13e70 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
13e80 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
13e90 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
13ea0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
13eb0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
13ec0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
13ed0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
13ee0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
13ef0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
13f00 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
13f10 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
13f20 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
13f30 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
13f40 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
13f50 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
13f60 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
13f70 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
13f80 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
13f90 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
13fa0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
13fb0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
13fc0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
13fd0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
13fe0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
13ff0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14000 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
14010 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
14020 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
14030 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
14040 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
14050 28 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  (In sqlite3_snpr
14060 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
14070 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e  s similar to "sn
14080 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a  printf()" from.*
14090 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  * the standard C
140a0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72   library.  The r
140b0 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e  esult is written
140c0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66   into the.** buf
140d0 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20  fer supplied as 
140e0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
140f0 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20  eter whose size 
14100 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74  is given by.** t
14110 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14120 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  er. Note that th
14130 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a  e order of the.*
14140 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61  * first two para
14150 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73  meters is revers
14160 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66  ed from snprintf
14170 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61  ().)^  This is a
14180 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20  n.** historical 
14190 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61  accident that ca
141a0 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69  nnot be fixed wi
141b0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a  thout breaking.*
141c0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
141d0 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f  atibility.  ^(No
141e0 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
141f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
14200 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
14210 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
14220 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
14230 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
14240 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
14250 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
14260 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57  the buffer.)^  W
14270 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20  e admit that.** 
14280 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
14290 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e  aracters written
142a0 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65   would be a more
142b0 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a   useful return.*
142c0 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63  * value but we c
142d0 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
142e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
142f0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
14300 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74  ntf().** now wit
14310 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f  hout breaking co
14320 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
14330 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74  ** ^As long as t
14340 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
14350 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
14360 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
14370 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
14380 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
14390 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
143a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
143b0 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20    ^The first.** 
143c0 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
143d0 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
143e0 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
143f0 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
14400 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
14410 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
14420 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
14430 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
14440 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
14450 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
14460 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
14470 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
14480 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
14490 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
144a0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
144b0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
144c0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
144d0 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
144e0 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
144f0 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
14500 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
14510 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
14520 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
14530 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
14540 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
14550 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
14560 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
14570 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
14580 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
14590 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
145a0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
145b0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
145c0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
145d0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
145e0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
145f0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
14600 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
14610 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
14620 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62  eral.)^  By doub
14630 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a  ling each '\''.*
14640 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65  * character it e
14650 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72  scapes that char
14660 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73  acter and allows
14670 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74   it to be insert
14680 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73  ed into.** the s
14690 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  tring..**.** For
146a0 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65   example, assume
146b0 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69   the string vari
146c0 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61  able zText conta
146d0 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c  ins text as foll
146e0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
146f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14700 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22   char *zText = "
14710 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
14720 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !";.** </pre></b
14730 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
14740 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69   One can use thi
14750 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c  s text in an SQL
14760 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f   statement as fo
14770 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
14780 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
14790 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
147a0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
147b0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
147c0 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22  le VALUES('%q')"
147d0 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
147e0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
147f0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
14800 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
14810 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
14820 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14830 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20  .** Because the 
14840 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  %q format string
14850 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c   is used, the '\
14860 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20  '' character in 
14870 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61  zText.** is esca
14880 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  ped and the SQL 
14890 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20  generated is as 
148a0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
148b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
148c0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
148d0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
148e0 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61  It''s a happy da
148f0 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!').** </pre></
14900 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
14910 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63  * This is correc
14920 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20  t.  Had we used 
14930 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71  %s instead of %q
14940 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  , the generated 
14950 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76  SQL.** would hav
14960 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68  e looked like th
14970 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  is:.**.** <block
14980 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
14990 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
149a0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20  e1 VALUES('It's 
149b0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a  a happy day!');.
149c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
149d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
149e0 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65  s second example
149f0 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61   is an SQL synta
14a00 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67  x error.  As a g
14a10 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20  eneral rule you 
14a20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73  should.** always
14a30 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20   use %q instead 
14a40 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72  of %s when inser
14a50 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61  ting text into a
14a60 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
14a70 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20  .**.** ^(The %Q 
14a80 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
14a90 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61  e %q except it a
14aa0 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20  lso adds single 
14ab0 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a  quotes around.**
14ac0 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20   the outside of 
14ad0 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67  the total string
14ae0 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  .  Additionally,
14af0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
14b00 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75  r in the.** argu
14b10 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e  ment list is a N
14b20 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20  ULL pointer, %Q 
14b30 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20  substitutes the 
14b40 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74  text "NULL" (wit
14b50 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71  hout.** single q
14b60 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66  uotes).)^  So, f
14b70 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20  or example, one 
14b80 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a  could say:.**.**
14b90 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14ba0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51  e>.**  char *zSQ
14bb0 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69  L = sqlite3_mpri
14bc0 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f  ntf("INSERT INTO
14bd0 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51   table VALUES(%Q
14be0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
14bf0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
14c00 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
14c10 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
14c20 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
14c30 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14c40 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61  **.** The code a
14c50 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72  bove will render
14c60 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73   a correct SQL s
14c70 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
14c80 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65  zSQL.** variable
14c90 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65   even if the zTe
14ca0 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  xt variable is a
14cb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
14cc0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
14cd0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
14ce0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
14cf0 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
14d00 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
14d10 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
14d20 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
14d30 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
14d40 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
14d50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
14d60 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
14d70 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
14d80 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
14d90 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
14da0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
14db0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
14dc0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
14dd0 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
14de0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14df0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
14e00 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
14e10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
14e20 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
14e30 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
14e40 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
14e50 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
14e60 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
14e70 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
14e80 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
14e90 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14ea0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
14eb0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
14ec0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
14ed0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
14ee0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
14ef0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
14f00 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
14f10 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
14f20 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
14f30 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
14f40 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
14f50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
14f60 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
14f70 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
14f80 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
14f90 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
14fa0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
14fb0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
14fc0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
14fd0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
14fe0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
14ff0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
15000 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
15010 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
15020 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
15030 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
15040 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
15050 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
15060 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
15070 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
15080 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
15090 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
150a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
150b0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
150c0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
150d0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
150e0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
150f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
15100 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15110 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
15120 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
15130 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
15140 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
15150 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
15160 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
15170 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
15180 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
15190 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
151a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
151b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
151c0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
151d0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
151e0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
151f0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
15200 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
15210 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
15220 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
15230 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
15240 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
15250 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
15260 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
15270 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
15280 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
15290 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
152a0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
152b0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
152c0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
152d0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
152e0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
152f0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
15300 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
15310 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
15320 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
15330 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
15340 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
15350 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
15360 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
15370 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
15380 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
15390 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
153a0 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
153b0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
153c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
153d0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
153e0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
153f0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
15400 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
15410 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
15420 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15430 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15440 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
15450 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
15460 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
15470 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
15480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
15490 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
154a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
154b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
154c0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
154d0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
154e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
154f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
15500 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
15510 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
15520 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
15530 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
15540 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
15550 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
15560 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
15570 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
15580 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
15590 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
155a0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
155b0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
155c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
155d0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
155e0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
155f0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
15600 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
15610 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
15620 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
15630 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
15640 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
15650 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
15660 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
15670 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
15680 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
15690 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
156a0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
156b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
156c0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
156d0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
156e0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
156f0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
15700 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
15710 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
15720 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
15730 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
15740 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
15750 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15760 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
15770 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
15780 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
15790 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
157a0 74 65 20 62 6f 75 6e 64 61 72 79 2e 0a 2a 2a 0a  te boundary..**.
157b0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
157c0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
157d0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
157e0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
157f0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
15800 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
15810 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
15820 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
15830 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
15840 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
15850 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
15860 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
15870 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
15880 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
15890 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
158a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
158b0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
158c0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
158d0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
158e0 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
158f0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
15900 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
15910 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
15920 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
15930 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
15940 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
15950 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
15960 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
15970 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
15980 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
15990 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
159a0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
159b0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
159c0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
159d0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
159e0 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
159f0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
15a00 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
15a10 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
15a20 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
15a30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
15a40 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
15a50 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
15a60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
15a70 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
15a80 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
15a90 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
15aa0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
15ab0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
15ac0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
15ad0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
15ae0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
15af0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
15b00 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
15b10 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
15b20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
15b30 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
15b40 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
15b50 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
15b60 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
15b70 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
15b80 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
15b90 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
15ba0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
15bb0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
15bc0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
15bd0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
15be0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
15bf0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
15c00 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
15c10 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
15c20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
15c30 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
15c40 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
15c50 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
15c60 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
15c70 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
15c80 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
15c90 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15ca0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
15cb0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
15cc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15cd0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
15ce0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
15cf0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
15d00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
15d10 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
15d20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
15d30 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
15d40 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
15d50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
15d60 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
15d70 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
15d80 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
15d90 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
15da0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
15db0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
15dc0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
15dd0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
15de0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
15df0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
15e00 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
15e10 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
15e20 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
15e30 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
15e40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
15e50 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
15e60 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
15e70 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
15e80 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
15e90 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
15ea0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
15eb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
15ec0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
15ed0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
15ee0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
15ef0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
15f00 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
15f10 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
15f20 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
15f30 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
15f40 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
15f50 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
15f60 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
15f70 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
15f80 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
15f90 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
15fa0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
15fb0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
15fc0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
15fd0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
15fe0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
15ff0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
16000 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
16010 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
16020 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
16030 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
16040 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
16050 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
16060 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
16070 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
16080 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
16090 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
160a0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
160b0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
160c0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
160d0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
160e0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
160f0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
16100 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
16110 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
16120 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
16130 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
16140 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
16150 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
16160 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
16170 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
16180 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
16190 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
161a0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
161b0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
161c0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
161d0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
161e0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
161f0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
16200 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
16210 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
16220 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
16230 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
16240 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
16250 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
16260 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
16270 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
16280 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
16290 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
162a0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
162b0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
162c0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
162d0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
162e0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
162f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
16300 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
16310 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
16320 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
16330 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
16340 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
16350 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
16360 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
16370 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
16380 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
16390 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
163a0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
163b0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
163c0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
163d0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
163e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
163f0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
16400 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
16410 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
16420 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
16430 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16440 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
16450 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
16460 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
16470 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
16480 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69  isters a authori
16490 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
164a0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
164b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
164c0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
164d0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
164e0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
164f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16500 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
16510 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
16520 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
16530 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
16540 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
16550 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
16560 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16570 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
16580 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
16590 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
165a0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
165b0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
165c0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
165d0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
165e0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
165f0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
16600 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
16610 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
16620 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16630 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16640 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
16650 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
16660 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
16670 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16680 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
16690 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
166a0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
166b0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
166c0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
166d0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
166e0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
166f0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
16700 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
16710 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
16720 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
16730 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
16740 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
16750 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
16760 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
16770 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
16780 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
16790 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
167a0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
167b0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
167c0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
167d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
167e0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
167f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16800 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
16810 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
16820 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
16830 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
16840 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
16850 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
16860 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
16870 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
16880 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
16890 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
168a0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
168b0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
168c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
168d0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
168e0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
168f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
16900 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
16910 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
16920 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
16930 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
16940 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
16950 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
16960 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
16970 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
16980 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
16990 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
169a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
169b0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
169c0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
169d0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
169e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
169f0 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
16a00 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16a10 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
16a20 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
16a30 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
16a40 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
16a50 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
16a60 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
16a70 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
16a80 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
16a90 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
16aa0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
16ab0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
16ac0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
16ad0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
16ae0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
16af0 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
16b00 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
16b10 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
16b20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
16b30 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
16b40 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
16b50 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
16b60 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
16b70 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
16b80 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
16b90 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
16ba0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
16bb0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
16bc0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
16bd0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
16be0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
16bf0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
16c00 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
16c10 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
16c20 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
16c30 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
16c40 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
16c50 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
16c60 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
16c70 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
16c80 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
16c90 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
16ca0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
16cb0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
16cc0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
16cd0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16ce0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
16cf0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
16d00 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
16d10 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
16d20 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
16d30 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
16d40 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
16d50 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
16d60 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
16d70 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
16d80 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
16d90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16da0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
16db0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
16dc0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
16dd0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
16de0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
16df0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
16e00 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
16e10 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
16e20 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
16e30 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
16e40 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
16e50 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
16e60 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
16e70 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
16e80 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
16e90 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
16ea0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
16eb0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
16ec0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
16ed0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
16ee0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
16ef0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
16f00 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
16f10 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
16f20 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
16f30 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
16f40 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
16f50 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
16f60 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
16f70 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
16f80 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
16f90 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
16fa0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
16fb0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
16fc0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
16fd0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
16fe0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
16ff0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
17000 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
17010 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
17020 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
17030 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
17040 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
17050 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
17060 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
17070 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
17080 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
17090 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
170a0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
170b0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
170c0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
170d0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
170e0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
170f0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
17100 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
17110 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
17120 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
17130 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
17140 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
17150 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
17160 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
17170 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
17180 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
17190 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
171a0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
171b0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
171c0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
171d0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
171e0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
171f0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
17200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
17210 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
17220 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
17230 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
17240 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
17250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17260 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
17270 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17280 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
17290 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
172a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
172b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
172c0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
172d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
172e0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
172f0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
17300 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
17310 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
17320 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
17330 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
17340 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
17350 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
17360 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
17370 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
17380 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
17390 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
173a0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
173b0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
173c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
173d0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
173e0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
173f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17400 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
17410 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
17420 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
17430 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
17440 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
17450 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17460 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
17470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
17480 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
17490 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
174a0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
174b0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
174c0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
174d0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
174e0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
174f0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
17500 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
17510 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
17520 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
17530 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
17540 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
17550 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
17560 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
17570 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
17580 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
17590 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
175a0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
175b0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
175c0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
175d0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
175e0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
175f0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
17600 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
17610 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
17620 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
17630 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
17640 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17650 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
17660 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
17670 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
17680 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
17690 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
176a0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
176b0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
176c0 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
176d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
176e0 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
176f0 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
17700 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
17710 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
17720 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
17730 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
17740 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
17750 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
17760 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
17770 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
17780 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
17790 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
177a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
177b0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
177c0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
177d0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
177e0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
177f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
17800 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
17810 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
17820 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17830 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
17840 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
17850 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
17860 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
17870 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
17880 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
17890 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
178a0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
178b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
178c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
178d0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
178e0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
178f0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
17900 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
17910 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
17920 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
17930 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
17940 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17950 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
17960 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
17970 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
17980 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
17990 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
179a0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
179b0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
179c0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
179d0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
179e0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
179f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
17a00 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
17a10 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
17a20 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
17a30 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
17a40 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
17a50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17a60 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
17a70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
17a80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17a90 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
17aa0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
17ab0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
17ac0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
17ad0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
17ae0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
17af0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
17b00 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
17b10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17b20 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
17b30 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
17b40 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
17b50 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
17b60 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
17b70 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
17b80 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
17b90 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
17ba0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
17bb0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
17bc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17bd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17be0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
17bf0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
17c00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17c10 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
17c20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
17c30 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
17c40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
17c50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17c60 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
17c70 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
17c80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
17c90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
17ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17cb0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
17cc0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
17cd0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
17ce0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
17cf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17d00 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
17d10 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
17d20 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
17d30 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
17d50 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
17d60 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
17d70 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
17d80 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
17da0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
17db0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
17dc0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
17dd0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
17df0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
17e00 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
17e10 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
17e20 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
17e30 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17e40 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
17e50 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
17e60 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
17e70 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17e80 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
17e90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
17ea0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
17eb0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
17ec0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
17ed0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
17ee0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
17ef0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
17f00 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
17f10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17f20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
17f30 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
17f40 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
17f50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
17f60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17f70 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
17f80 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
17f90 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
17fa0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
17fb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17fc0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
17fd0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
17fe0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17ff0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18000 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18010 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
18020 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
18030 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
18040 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18050 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18060 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
18070 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
18080 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
18090 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
180a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
180b0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
180c0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
180d0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
180e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
180f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18100 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
18110 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
18120 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
18130 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18150 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
18160 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
18170 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18180 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
181a0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
181b0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
181c0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
181d0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
181e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
181f0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
18200 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
18210 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
18220 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
18230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
18240 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
18250 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
18260 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
18270 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
18290 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
182a0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
182b0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
182c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
182d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
182e0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
182f0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
18300 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
18310 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
18320 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
18330 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18340 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
18350 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
18360 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18370 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
18380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18390 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
183a0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
183b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
183c0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
183d0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
183e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
183f0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
18400 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18410 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
18420 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
18430 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
18440 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18450 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18460 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
18470 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
18480 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18490 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
184a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
184b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
184c0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
184d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
184e0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
184f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18500 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
18510 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
18520 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18530 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
18540 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18550 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
18560 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
18570 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18580 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
18590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
185a0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
185b0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
185c0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
185d0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
185e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
185f0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
18600 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
18610 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
18620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18630 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
18640 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
18650 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  s.** EXPERIMENTA
18660 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  L.**.** These ro
18670 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
18680 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18690 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
186a0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
186b0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
186c0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
186d0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
186e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
186f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
18700 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
18710 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
18720 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
18730 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
18740 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18750 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
18760 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
18770 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
18780 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
18790 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
187a0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
187b0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
187c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
187d0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
187e0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
187f0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
18800 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
18810 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
18820 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
18830 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
18840 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
18850 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
18860 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
18870 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
18880 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
18890 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
188a0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
188b0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  igger.)^.**.** ^
188c0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
188d0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
188e0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
188f0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
18900 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
18910 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
18920 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
18930 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
18940 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
18950 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
18960 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
18970 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
18980 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
18990 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
189a0 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
189b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
189c0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71  IMENTAL void *sq
189d0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
189e0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
189f0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
18a00 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
18a10 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
18a20 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
18a30 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
18a40 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
18a50 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
18a60 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
18a70 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
18a80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18a90 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
18aa0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
18ab0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
18ac0 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c  configures a cal
18ad0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d  lback function -
18ae0 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73   the.** progress
18af0 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74   callback - that
18b00 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   is invoked peri
18b10 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
18b20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  long.** running 
18b30 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
18b40 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
18b50 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a  te3_step()] and.
18b60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
18b70 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78  table()].  An ex
18b80 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
18b90 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
18ba0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
18bb0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
18bc0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
18bd0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
18be0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
18bf0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
18c00 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
18c10 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
18c20 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
18c30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
18c40 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
18c50 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
18c60 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
18c70 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
18c80 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
18c90 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
18ca0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
18cb0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
18cc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18cd0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
18ce0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
18cf0 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
18d00 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
18d10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
18d20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
18d30 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
18d40 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
18d50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
18d60 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
18d70 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
18d80 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
18d90 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
18da0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
18db0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
18dc0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
18dd0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
18de0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
18df0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
18e00 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onnection.**.** 
18e10 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
18e20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
18e30 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f  atabase file who
18e40 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e  se name is given
18e50 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   by the.** filen
18e60 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54  ame argument. ^T
18e70 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
18e80 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
18e90 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
18ea0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
18eb0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
18ec0 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
18ed0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
18ee0 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
18ef0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
18f00 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61  pen16(). ^(A [da
18f10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18f20 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75  n] handle is usu
18f30 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ally.** returned
18f40 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20   in *ppDb, even 
18f50 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  if an error occu
18f60 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78  rs.  The only ex
18f70 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a  ception is that.
18f80 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
18f90 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
18fa0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
18fb0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  d the [sqlite3] 
18fc0 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c  object,.** a NUL
18fd0 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65  L will be writte
18fe0 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73  n into *ppDb ins
18ff0 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65  tead of a pointe
19000 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
19010 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20  3].** object.)^ 
19020 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73  ^(If the databas
19030 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
19040 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
19050 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
19060 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
19070 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
19080 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
19090 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
190a0 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73  ed.)^ ^The.** [s
190b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
190c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
190d0 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
190e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
190f0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
19100 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
19110 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
19120 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e  e error followin
19130 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61  g a failure of a
19140 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  ny.** of the sql
19150 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74  ite3_open() rout
19160 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ines..**.** ^The
19170 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
19180 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
19190 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
191a0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
191b0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
191c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
191d0 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
191e0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
191f0 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
19200 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
19210 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
19220 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
19230 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
19240 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
19250 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
19260 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
19270 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
19280 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
19290 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
192a0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
192b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
192c0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
192d0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
192e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
192f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
19300 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
19310 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
19320 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
19330 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
19340 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19350 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
19360 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
19370 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
19380 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
19390 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
193a0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
193b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
193c0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
193d0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
193e0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
193f0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
19400 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
19410 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
19420 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
19430 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
19440 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
19450 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
19460 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  .** and/or [SQLI
19470 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
19480 41 43 48 45 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  ACHE] flags:)^.*
19490 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
194a0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
194b0 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
194c0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
194d0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
194e0 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
194f0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
19500 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
19510 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
19520 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
19530 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
19540 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
19550 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
19560 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
19570 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19580 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
19590 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
195a0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
195b0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
195c0 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
195d0 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
195e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
195f0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
19600 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
19610 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
19620 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
19630 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
19640 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
19650 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
19660 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
19670 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
19680 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
19690 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
196a0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
196b0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
196c0 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 73  , and is creates
196d0 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65   it if.** it doe
196e0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
196f0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
19700 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
19710 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
19720 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
19730 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
19740 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
19750 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
19760 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
19770 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
19780 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
19790 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
197a0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
197b0 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f  n above or one o
197c0 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f  f the combinatio
197d0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63  ns shown above c
197e0 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20  ombined.** with 
197f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
19800 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
19810 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
19820 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  X],.** [SQLITE_O
19830 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
19840 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
19850 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
19860 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e  ] flags,.** then
19870 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
19880 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
19890 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
198a0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
198b0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
198c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
198d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
198e0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
198f0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
19900 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
19910 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
19920 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
19930 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
19940 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
19950 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
19960 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
19970 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
19980 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
19990 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
199a0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
199b0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
199c0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
199d0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
199e0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
199f0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
19a00 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
19a10 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
19a20 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
19a30 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
19a40 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
19a50 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
19a60 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
19a70 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
19a80 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
19a90 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
19aa0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
19ab0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
19ac0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
19ad0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19ae0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
19af0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
19b00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
19b10 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
19b20 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
19b30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19b40 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
19b50 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
19b60 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
19b70 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
19b80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
19b90 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
19ba0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
19bb0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
19bc0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
19bd0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
19be0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
19bf0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
19c00 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
19c10 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
19c20 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
19c30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
19c40 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
19c50 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
19c60 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
19c70 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
19c80 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
19c90 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
19ca0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
19cb0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
19cc0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
19cd0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
19ce0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
19cf0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
19d00 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
19d10 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
19d20 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
19d30 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
19d40 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
19d50 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
19d60 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
19d70 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
19d80 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
19d90 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
19da0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
19db0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
19dc0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
19dd0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
19de0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
19df0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
19e00 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
19e10 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
19e20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19e30 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
19e40 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
19e50 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19e60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
19e70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
19e80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
19e90 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
19ea0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
19eb0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
19ec0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
19ed0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
19ee0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
19ef0 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
19f00 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
19f10 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
19f20 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
19f30 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
19f40 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
19f50 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
19f60 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
19f70 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
19f80 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
19f90 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
19fa0 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
19fb0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19fc0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
19fd0 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
19fe0 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
19ff0 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
1a000 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
1a010 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
1a020 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
1a030 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
1a040 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
1a050 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
1a060 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
1a070 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
1a080 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
1a090 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f 0a  3_open_v2()..*/.
1a0a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1a0b0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1a0c0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1a0d0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1a0e0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1a0f0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1a100 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1a110 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1a120 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1a130 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
1a140 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
1a150 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1a160 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
1a170 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1a180 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1a190 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1a1a0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1a1b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a1c0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1a1d0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1a1e0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1a1f0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1a200 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
1a210 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1a220 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1a230 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
1a240 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
1a250 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
1a260 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
1a270 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
1a280 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
1a290 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
1a2a0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
1a2b0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
1a2c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a2d0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
1a2e0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1a2f0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
1a300 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
1a310 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1a320 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
1a330 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
1a340 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
1a350 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
1a360 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1a370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
1a380 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
1a390 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
1a3a0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1a3b0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
1a3c0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
1a3d0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
1a3e0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1a3f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
1a400 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
1a410 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
1a420 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
1a430 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
1a440 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
1a450 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
1a460 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1a470 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
1a480 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
1a490 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
1a4a0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1a4b0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1a4c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1a4d0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1a4e0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1a4f0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1a500 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1a510 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1a520 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1a530 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
1a540 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
1a550 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
1a560 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
1a570 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
1a580 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1a590 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
1a5a0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
1a5b0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
1a5c0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
1a5d0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
1a5e0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
1a5f0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
1a600 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
1a610 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
1a620 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
1a630 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
1a640 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ^.**.** When the
1a650 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1a660 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
1a670 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
1a680 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
1a690 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
1a6a0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
1a6b0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a6c0 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
1a6d0 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
1a6e0 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
1a6f0 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
1a700 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
1a710 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
1a720 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
1a730 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
1a740 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
1a750 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
1a760 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
1a770 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
1a780 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
1a790 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
1a7a0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
1a7b0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
1a7c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1a7d0 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
1a7e0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
1a7f0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
1a800 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
1a810 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
1a820 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
1a830 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
1a840 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
1a850 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
1a860 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
1a870 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
1a880 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
1a890 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
1a8a0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
1a8b0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1a8c0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1a8d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1a8e0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1a8f0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1a900 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1a910 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1a920 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1a930 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1a940 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1a950 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1a960 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
1a970 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1a980 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
1a990 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
1a9a0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
1a9b0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
1a9c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
1a9d0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
1a9e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1a9f0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
1aa00 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1aa10 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
1aa20 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
1aa30 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
1aa40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
1aa50 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1aa60 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
1aa70 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
1aa80 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
1aa90 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
1aaa0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
1aab0 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
1aac0 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
1aad0 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
1aae0 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
1aaf0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
1ab00 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
1ab10 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
1ab20 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
1ab30 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
1ab40 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
1ab50 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
1ab60 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1ab70 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
1ab80 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
1ab90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1aba0 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
1abb0 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
1abc0 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
1abd0 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
1abe0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
1abf0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
1ac00 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
1ac10 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
1ac20 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
1ac30 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
1ac40 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
1ac50 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
1ac60 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
1ac70 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
1ac80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1ac90 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
1aca0 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
1acb0 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
1acc0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1acd0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
1ace0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1acf0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1ad00 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
1ad10 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
1ad20 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
1ad30 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
1ad40 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
1ad50 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1ad60 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
1ad70 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1ad80 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
1ad90 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
1ada0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
1adb0 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  mits.**.** ^(Thi
1adc0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1add0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
1ade0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
1adf0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
1ae00 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
1ae10 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
1ae20 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
1ae30 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1ae40 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
1ae50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
1ae60 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
1ae70 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
1ae80 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1ae90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1aea0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
1aeb0 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
1aec0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
1aed0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
1aee0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
1aef0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
1af00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1af10 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
1af20 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
1af30 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
1af40 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20  returns the old 
1af50 6c 69 6d 69 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  limit.)^.**.** ^
1af60 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1af70 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1af80 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1af90 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1afa0 2a 20 5e 28 46 6f 72 20 74 68 65 20 6c 69 6d 69  * ^(For the limi
1afb0 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53 51  t category of SQ
1afc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74  LITE_LIMIT_XYZ t
1afd0 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c  here is a .** [l
1afe0 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70  imits | hard upp
1aff0 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74  er bound].** set
1b000 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69   by a compile-ti
1b010 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  me C preprocesso
1b020 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20 0a 2a  r macro named .*
1b030 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
1b040 54 45 5f 4d 41 58 5f 58 59 5a 5d 2e 0a 2a 2a 20  TE_MAX_XYZ]..** 
1b050 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
1b060 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
1b070 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
1b080 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
1b090 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
1b0a0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
1b0b0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1b0c0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
1b0d0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
1b0e0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
1b0f0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  nd..**.** Run-ti
1b100 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
1b110 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
1b120 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
1b130 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
1b140 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
1b150 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
1b160 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
1b170 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
1b180 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
1b190 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
1b1a0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
1b1b0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
1b1c0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
1b1d0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
1b1e0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
1b1f0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
1b200 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
1b210 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
1b220 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
1b230 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
1b240 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
1b250 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
1b260 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
1b270 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
1b280 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
1b290 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
1b2a0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
1b2b0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
1b2c0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
1b2d0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
1b2e0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
1b2f0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
1b300 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
1b310 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
1b320 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
1b330 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
1b340 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
1b350 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1b360 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
1b370 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
1b380 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
1b390 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
1b3a0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
1b3b0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
1b3c0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
1b3d0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
1b3e0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
1b3f0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
1b400 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
1b410 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
1b420 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
1b430 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
1b440 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
1b450 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
1b460 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
1b470 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
1b480 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
1b490 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
1b4a0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
1b4b0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
1b4c0 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
1b4d0 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
1b4e0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
1b4f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
1b500 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
1b510 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
1b520 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
1b530 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
1b540 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b550 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
1b560 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
1b570 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
1b580 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
1b590 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
1b5a0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
1b5b0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
1b5c0 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
1b5d0 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
1b5e0 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
1b5f0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  >.** ^(<dt>SQLIT
1b600 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
1b610 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1b620 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
1b630 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
1b640 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c  B or table row.<
1b650 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1b660 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
1b670 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
1b680 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1b690 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
1b6a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
1b6b0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
1b6c0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1b6d0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
1b6e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1b6f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1b700 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
1b710 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
1b720 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
1b730 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1b740 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
1b750 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
1b760 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
1b770 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
1b780 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
1b790 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
1b7a0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1b7b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1b7c0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
1b7d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
1b7e0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
1b7f0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
1b800 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
1b810 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1b820 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1b830 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
1b840 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1b850 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1b860 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1b870 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1b880 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1b890 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1b8a0 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
1b8b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1b8c0 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
1b8d0 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
1b8e0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
1b8f0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
1b900 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
1b910 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1b920 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1b930 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
1b940 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
1b950 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1b960 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
1b970 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
1b980 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1b990 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1b9a0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
1b9b0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1b9c0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
1b9d0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
1b9e0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
1b9f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  /dd>.**.** ^(<dt
1ba00 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
1ba10 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
1ba20 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1ba30 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1ba40 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
1ba50 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1ba60 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
1ba70 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
1ba80 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1ba90 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1baa0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
1bab0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1bac0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1bad0 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e   variables in an
1bae0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1baf0 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f  hat can.** be bo
1bb00 75 6e 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  und.</dd>)^.**.*
1bb10 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1bb20 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
1bb30 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1bb40 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1bb50 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
1bb60 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
1bb70 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
1bb80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1bb90 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
1bba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
1bbb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1bbc0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
1bbd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1bbe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1bbf0 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
1bc00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1bc10 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
1bc20 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
1bc30 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1bc40 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
1bc50 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1bc60 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1bc70 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
1bc80 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
1bc90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1bca0 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
1bcb0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
1bcc0 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
1bcd0 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
1bce0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
1bcf0 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
1bd00 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
1bd10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
1bd20 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
1bd30 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
1bd40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1bd50 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
1bd60 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
1bd70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
1bd80 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
1bd90 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a         10../*.**
1bda0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1bdb0 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
1bdc0 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  ement.** KEYWORD
1bdd0 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e  S: {SQL statemen
1bde0 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a  t compiler}.**.*
1bdf0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20  * To execute an 
1be00 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75  SQL query, it mu
1be10 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
1be20 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
1be30 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
1be40 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
1be50 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
1be60 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
1be70 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
1be80 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1be90 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
1bea0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
1beb0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
1bec0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
1bed0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1bee0 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
1bef0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1bf00 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
1bf10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
1bf20 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
1bf30 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
1bf40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1bf50 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
1bf60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
1bf70 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
1bf80 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
1bf90 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1bfa0 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
1bfb0 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
1bfc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bfd0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
1bfe0 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
1bff0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1c000 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
1c010 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
1c020 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
1c030 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
1c040 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65  e argument is le
1c050 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68  ss than zero, th
1c060 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
1c070 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
1c080 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1c090 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
1c0a0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1c0b0 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
1c0c0 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
1c0d0 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
1c0e0 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e  rom zSql.  ^When
1c0f0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
1c100 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a  gative, the.** z
1c110 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20  Sql string ends 
1c120 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69  at either the fi
1c130 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c  rst '\000' or '\
1c140 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72  u0000' character
1c150 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65   or.** the nByte
1c160 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65  -th byte, whiche
1c170 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e  ver comes first.
1c180 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
1c190 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  nows.** that the
1c1a0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
1c1b0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
1c1c0 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69  ed, then there i
1c1d0 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72  s a small.** per
1c1e0 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
1c1f0 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20  ge to be gained 
1c200 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  by passing an nB
1c210 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
1c220 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74  at.** is equal t
1c230 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  o the number of 
1c240 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
1c250 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
1c260 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
1c270 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
1c280 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49   bytes..**.** ^I
1c290 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
1c2a0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
1c2b0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
1c2c0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
1c2d0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
1c2e0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
1c2f0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
1c300 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
1c310 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
1c320 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
1c330 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
1c340 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
1c350 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
1c360 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
1c370 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
1c380 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
1c390 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
1c3a0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
1c3b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1c3c0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
1c3d0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
1c3e0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1c3f0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
1c400 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
1c410 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
1c420 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
1c430 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1c440 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
1c450 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
1c460 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
1c470 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
1c480 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
1c490 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
1c4a0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
1c4b0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
1c4c0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
1c4d0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
1c4e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
1c4f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1c500 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
1c510 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1c520 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
1c530 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
1c540 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
1c550 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
1c560 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
1c570 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
1c580 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1c590 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
1c5a0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1c5b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1c5c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
1c5d0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
1c5e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1c5f0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
1c600 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
1c610 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
1c620 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
1c630 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
1c640 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
1c650 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
1c660 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
1c670 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
1c680 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
1c690 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
1c6a0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
1c6b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c6c0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
1c6d0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
1c6e0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
1c6f0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
1c700 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
1c710 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
1c720 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
1c730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
1c740 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
1c750 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
1c760 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
1c770 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1c780 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
1c790 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
1c7a0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
1c7b0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
1c7c0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
1c7d0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
1c7e0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
1c7f0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
1c800 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1c810 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
1c820 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
1c830 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
1c840 61 69 6e 2e 20 20 5e 49 66 20 74 68 65 20 73 63  ain.  ^If the sc
1c850 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64  hema has changed
1c860 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61   in.** a way tha
1c870 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74  t makes the stat
1c880 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20  ement no longer 
1c890 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f  valid, [sqlite3_
1c8a0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69  step()] will sti
1c8b0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
1c8c0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42  LITE_SCHEMA].  B
1c8d0 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65  ut unlike the le
1c8e0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b  gacy behavior, [
1c8f0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69  SQLITE_SCHEMA] i
1c900 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c  s.** now a fatal
1c910 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67   error.  Calling
1c920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c930 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69  e_v2()] again wi
1c940 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a  ll not make the.
1c950 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79  ** error go away
1c960 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71  .  Note: use [sq
1c970 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
1c980 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78 74  to find the text
1c990 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69  .** of the parsi
1c9a0 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72 65  ng error that re
1c9b0 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c  sults in an [SQL
1c9c0 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75  ITE_SCHEMA] retu
1c9d0 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  rn..** </li>.**.
1c9e0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
1c9f0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1ca00 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1ca10 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
1ca20 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
1ca30 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
1ca40 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
1ca50 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
1ca60 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
1ca70 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
1ca80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ca90 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
1caa0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
1cab0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
1cac0 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
1cad0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1cae0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1caf0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1cb00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1cb10 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
1cb20 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
1cb30 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1cb40 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1cb50 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1cb60 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1cb70 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1cb80 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1cb90 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1cba0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1cbb0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1cbc0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
1cbd0 76 61 6c 75 65 20 6f 66 20 61 20 5b 70 61 72 61  value of a [para
1cbe0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
1cbf0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 57  ameter] in the W
1cc00 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68  HERE clause migh
1cc10 74 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  t.** change the 
1cc20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
1cc30 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 6e   statement, then
1cc40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6d   the statement m
1cc50 61 79 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ay be.** automat
1cc60 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
1cc70 64 20 28 61 73 20 69 66 20 74 68 65 72 65 20 68  d (as if there h
1cc80 61 64 20 62 65 65 6e 20 61 20 73 63 68 65 6d 61  ad been a schema
1cc90 20 63 68 61 6e 67 65 29 20 6f 6e 20 74 68 65 20   change) on the 
1cca0 66 69 72 73 74 20 0a 2a 2a 20 5b 73 71 6c 69 74  first .** [sqlit
1ccb0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
1ccc0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
1ccd0 61 6e 67 65 20 74 6f 20 74 68 65 20 0a 2a 2a 20  ange to the .** 
1cce0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
1ccf0 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  xt | bindings] o
1cd00 66 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  f the [parameter
1cd10 5d 2e 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ]. .** </li>.** 
1cd20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ol>.*/.int sql
1cd30 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
1cd40 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1cd50 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1cd60 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1cd70 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1cd80 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1cd90 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1cda0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1cdb0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1cdc0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1cdd0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1cde0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1cdf0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1ce00 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1ce10 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1ce20 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1ce30 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1ce40 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1ce50 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1ce60 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1ce70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ce80 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1ce90 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1cea0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1ceb0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1cec0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1ced0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1cee0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1cef0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1cf00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1cf10 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1cf20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1cf30 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1cf40 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1cf50 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1cf60 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1cf70 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1cf80 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1cf90 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1cfa0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1cfb0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1cfc0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
1cfd0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1cfe0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1cff0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1d000 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1d010 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1d020 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1d030 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1d040 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1d050 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1d060 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1d070 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1d080 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1d090 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1d0a0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1d0b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1d0c0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1d0d0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1d0e0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1d0f0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1d100 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1d110 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d120 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1d130 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1d140 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1d150 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1d160 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1d170 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1d180 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1d190 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1d1a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1d1b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1d1c0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1d1d0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1d1e0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1d1f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1d200 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1d210 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1d220 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1d230 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1d240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d250 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
1d260 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
1d270 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
1d280 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1d290 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
1d2a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
1d2b0 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
1d2c0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
1d2d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
1d2e0 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
1d2f0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
1d300 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
1d310 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
1d320 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1d330 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d340 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f  e16_v2()]..*/.co
1d350 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1d360 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
1d370 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
1d380 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
1d390 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
1d3a0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
1d3b0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
1d3c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1d3d0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
1d3e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
1d3f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
1d400 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
1d410 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
1d420 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
1d430 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
1d440 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
1d450 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
1d460 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
1d470 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
1d480 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
1d490 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
1d4a0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
1d4b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
1d4c0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
1d4d0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
1d4e0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
1d4f0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
1d500 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
1d510 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1d520 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
1d530 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
1d540 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
1d550 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
1d560 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
1d570 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1d580 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
1d590 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
1d5a0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
1d5b0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
1d5c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1d5d0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
1d5e0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
1d5f0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
1d600 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
1d610 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
1d620 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
1d630 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
1d640 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1d650 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
1d660 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
1d670 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
1d680 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
1d690 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
1d6a0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69  ex is held.  A i
1d6b0 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
1d6c0 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
1d6d0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1d6e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
1d6f0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
1d700 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
1d710 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1d720 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
1d730 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1d740 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
1d750 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
1d760 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
1d770 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
1d780 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
1d790 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
1d7a0 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
1d7b0 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
1d7c0 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
1d7d0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
1d7e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1d7f0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
1d800 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1d810 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
1d820 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
1d830 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
1d840 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
1d850 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
1d860 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1d870 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
1d880 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
1d890 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
1d8a0 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
1d8b0 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
1d8c0 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
1d8d0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
1d8e0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
1d8f0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
1d900 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1d910 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
1d920 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
1d930 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
1d940 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
1d950 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
1d960 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
1d970 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1d980 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74  _value objects t
1d990 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61  hat are passed a
1d9a0 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74  s parameters int
1d9b0 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  o the.** impleme
1d9c0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c  ntation of [appl
1d9d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1d9e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61  SQL functions] a
1d9f0 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a  re protected..**
1da00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
1da10 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
1da20 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
1da30 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
1da40 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
1da50 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
1da60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
1da70 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
1da80 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
1da90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
1daa0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
1dab0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1dac0 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
1dad0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
1dae0 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
1daf0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
1db00 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
1db10 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
1db20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1db30 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
1db40 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
1db50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
1db60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1db70 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
1db80 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  text Object.**.*
1db90 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
1dba0 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
1dbb0 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
1dbc0 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
1dbd0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
1dbe0 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70  xt object.  ^A p
1dbf0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c  ointer to an sql
1dc00 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
1dc10 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ect.** is always
1dc20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1dc30 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   to [application
1dc40 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
1dc50 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20  ctions]..** The 
1dc60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
1dc70 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
1dc80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1dc90 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a  will pass this.*
1dca0 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67  * pointer throug
1dcb0 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20  h into calls to 
1dcc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
1dcd0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65  int | sqlite3_re
1dce0 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  sult()],.** [sql
1dcf0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
1dd00 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69  ontext()], [sqli
1dd10 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
1dd20 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ,.** [sqlite3_co
1dd30 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
1dd40 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  )], [sqlite3_get
1dd50 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  _auxdata()],.** 
1dd60 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f  and/or [sqlite3_
1dd70 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a  set_auxdata()]..
1dd80 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1dd90 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
1dda0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t sqlite3_contex
1ddb0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
1ddc0 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75  EF: Binding Valu
1ddd0 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53  es To Prepared S
1dde0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59  tatements.** KEY
1ddf0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
1de00 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
1de10 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
1de20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
1de30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1de40 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
1de50 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
1de60 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
1de70 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
1de80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1de90 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
1dea0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1deb0 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
1dec0 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
1ded0 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
1dee0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
1def0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
1df00 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
1df10 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
1df20 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1df30 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1df40 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1df50 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1df60 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1df70 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1df80 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
1df90 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
1dfa0 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
1dfb0 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
1dfc0 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
1dfd0 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
1dfe0 6e 74 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20  ntifer.)^  ^The 
1dff0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
1e000 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
1e010 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
1e020 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
1e030 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
1e040 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1e050 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1e060 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1e070 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1e080 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
1e090 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1e0a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1e0b0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1e0c0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
1e0d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1e0e0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1e0f0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
1e100 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
1e110 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1e120 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
1e130 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
1e140 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1e150 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
1e160 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
1e170 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
1e180 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
1e190 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1e1a0 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
1e1b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
1e1c0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
1e1d0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
1e1e0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
1e1f0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
1e200 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
1e210 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
1e220 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
1e230 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
1e240 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
1e250 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
1e260 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
1e270 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
1e280 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1e290 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
1e2a0 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
1e2b0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1e2c0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1e2d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1e2e0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
1e2f0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
1e300 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
1e310 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
1e320 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
1e330 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
1e340 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
1e350 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
1e360 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
1e370 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1e380 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
1e390 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
1e3a0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  meter..**.** ^(I
1e3b0 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
1e3c0 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
1e3d0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
1e3e0 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
1e3f0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
1e400 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
1e410 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
1e420 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
1e430 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1e440 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
1e450 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
1e460 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1e470 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
1e480 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1e490 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1e4a0 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
1e4b0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
1e4c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1e4d0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1e4e0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1e4f0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  inator..**.** ^T
1e500 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1e510 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
1e520 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
1e530 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
1e540 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
1e550 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
1e560 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
1e570 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
1e580 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
1e590 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
1e5a0 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
1e5b0 69 74 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20  ith it. ^If the 
1e5c0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
1e5d0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
1e5e0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
1e5f0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
1e600 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
1e610 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
1e620 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
1e630 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
1e640 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
1e650 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
1e660 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
1e670 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
1e680 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
1e690 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
1e6a0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
1e6b0 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
1e6c0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
1e6d0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
1e6e0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
1e6f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1e700 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
1e710 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e720 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1e730 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
1e740 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
1e750 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
1e760 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
1e770 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
1e780 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
1e790 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
1e7a0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
1e7b0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
1e7c0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
1e7d0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
1e7e0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
1e7f0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
1e800 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
1e810 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
1e820 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
1e830 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
1e840 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1e850 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
1e860 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
1e870 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
1e880 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
1e890 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1e8a0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1e8b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1e8c0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
1e8d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1e8e0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1e8f0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
1e900 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1e910 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
1e920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e930 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
1e940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
1e950 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
1e960 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
1e970 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
1e980 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
1e990 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1e9a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
1e9b0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
1e9c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
1e9d0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
1e9e0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
1e9f0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
1ea00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ea10 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
1ea20 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
1ea30 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
1ea40 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
1ea50 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
1ea60 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
1ea70 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
1ea80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
1ea90 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
1eaa0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
1eab0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
1eac0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
1ead0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eae0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
1eaf0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1eb00 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1eb10 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
1eb20 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
1eb30 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
1eb40 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
1eb50 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1eb60 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
1eb70 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
1eb80 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
1eb90 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
1eba0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
1ebb0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
1ebc0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1ebd0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ebe0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
1ebf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ec00 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1ec10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1ec20 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1ec30 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1ec40 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
1ec50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1ec60 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1ec70 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
1ec80 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1ec90 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
1eca0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ecb0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
1ecc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
1ecd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1ece0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
1ecf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
1ed00 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
1ed10 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
1ed20 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
1ed30 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
1ed40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1ed50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1ed60 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
1ed70 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1ed80 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
1ed90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1eda0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1edb0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
1edc0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1edd0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
1ede0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
1edf0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1ee00 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
1ee10 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1ee20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
1ee30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1ee40 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
1ee50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
1ee60 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
1ee70 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
1ee80 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
1ee90 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1eea0 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
1eeb0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
1eec0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
1eed0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
1eee0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1eef0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
1ef00 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
1ef10 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
1ef20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
1ef30 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
1ef40 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
1ef50 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
1ef60 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
1ef70 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
1ef80 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
1ef90 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
1efa0 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
1efb0 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
1efc0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
1efd0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
1efe0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1eff0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
1f000 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
1f010 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
1f020 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
1f030 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
1f040 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
1f050 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
1f060 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
1f070 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1f080 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
1f090 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
1f0a0 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
1f0b0 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
1f0c0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1f0d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1f0e0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1f0f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1f100 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
1f110 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1f120 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f130 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
1f140 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1f150 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
1f160 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1f170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1f180 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
1f190 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
1f1a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1f1b0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
1f1c0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
1f1d0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
1f1e0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
1f1f0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
1f200 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1f210 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
1f220 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
1f230 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
1f240 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1f250 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1f260 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
1f270 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
1f280 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
1f290 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1f2a0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
1f2b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
1f2c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1f2d0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
1f2e0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
1f2f0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
1f300 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
1f310 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
1f320 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1f330 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
1f340 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
1f350 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
1f360 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
1f370 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
1f380 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
1f390 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
1f3a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1f3b0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
1f3c0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
1f3d0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
1f3e0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
1f3f0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1f400 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
1f410 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1f420 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
1f430 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
1f440 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
1f450 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
1f460 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
1f470 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
1f480 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
1f490 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
1f4a0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
1f4b0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
1f4c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1f4d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1f4e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1f4f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1f500 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1f510 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
1f520 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1f530 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f540 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
1f550 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f560 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1f570 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
1f580 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
1f590 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
1f5a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f5b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f5c0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
1f5d0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
1f5e0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
1f5f0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
1f600 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
1f610 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
1f620 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
1f630 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
1f640 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
1f650 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
1f660 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
1f670 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
1f680 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1f690 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
1f6a0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
1f6b0 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
1f6c0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
1f6d0 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
1f6e0 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
1f6f0 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
1f700 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
1f710 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1f720 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
1f730 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
1f740 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
1f750 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1f760 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
1f770 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1f780 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1f790 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1f7a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1f7b0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
1f7c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1f7d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1f7e0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
1f7f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1f800 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
1f810 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
1f820 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
1f830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1f840 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
1f850 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
1f860 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
1f870 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65  ^Contrary to the
1f880 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61   intuition of ma
1f890 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ny, [sqlite3_res
1f8a0 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72  et()] does not r
1f8b0 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  eset.** the [sql
1f8c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
1f8d0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20   bindings] on a 
1f8e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f8f0 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68  ent]..** ^Use th
1f900 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
1f910 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
1f920 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
1f930 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f940 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
1f950 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
1f960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f970 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
1f980 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
1f990 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
1f9a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1f9b0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
1f9c0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
1f9d0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
1f9e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
1f9f0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1fa00 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
1fa10 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
1fa20 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
1fa30 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
1fa40 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
1fa50 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2f  an [UPDATE])..*/
1fa60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
1fa70 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
1fa80 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1fa90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1faa0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
1fab0 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
1fac0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1fad0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
1fae0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
1faf0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
1fb00 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
1fb10 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
1fb20 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1fb30 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1fb40 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
1fb50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1fb60 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1fb70 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1fb80 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
1fb90 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
1fba0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
1fbb0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1fbc0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1fbd0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1fbe0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
1fbf0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1fc00 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1fc10 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
1fc20 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
1fc30 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
1fc40 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
1fc50 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1fc60 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
1fc70 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
1fc80 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
1fc90 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
1fca0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1fcb0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
1fcc0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
1fcd0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1fce0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
1fcf0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
1fd00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1fd10 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
1fd20 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
1fd30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1fd40 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
1fd50 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
1fd60 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
1fd70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
1fd80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
1fd90 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
1fda0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
1fdb0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
1fdc0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
1fdd0 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
1fde0 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
1fdf0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
1fe00 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
1fe10 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1fe20 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
1fe30 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
1fe40 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
1fe50 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
1fe60 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
1fe70 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
1fe80 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
1fe90 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
1fea0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
1feb0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
1fec0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
1fed0 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
1fee0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
1fef0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
1ff00 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
1ff10 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1ff20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
1ff30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ff40 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
1ff50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1ff60 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1ff70 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
1ff80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ff90 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
1ffa0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
1ffb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1ffc0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
1ffd0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
1ffe0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
1fff0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
20000 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
20010 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
20020 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
20030 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
20040 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
20050 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
20060 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
20070 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
20080 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
20090 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
200a0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
200b0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
200c0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
200d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
200e0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
200f0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
20100 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
20110 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
20120 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
20130 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
20140 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
20150 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
20160 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
20170 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
20180 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20190 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
201a0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
201b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
201c0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
201d0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
201e0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
201f0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
20200 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
20210 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
20220 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
20230 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
20240 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
20250 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
20260 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
20270 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
20280 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
20290 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
202a0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
202b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
202c0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
202d0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
202e0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
202f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
20300 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
20310 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
20320 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
20330 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
20340 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
20350 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
20360 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
20370 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
20380 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
20390 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
203a0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
203b0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
203c0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
203d0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
203e0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
203f0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
20400 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
20410 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
20420 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
20430 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
20440 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
20450 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
20460 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
20470 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
20480 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
20490 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
204a0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
204b0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
204c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
204d0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
204e0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
204f0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
20500 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
20510 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
20520 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
20530 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
20540 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
20550 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
20560 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
20570 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
20580 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
20590 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
205a0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
205b0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
205c0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
205d0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
205e0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
205f0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
20600 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
20610 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
20620 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
20630 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
20640 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
20650 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
20660 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
20670 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
20680 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
20690 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
206a0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
206b0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
206c0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
206d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
206e0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
206f0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
20700 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
20710 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
20720 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
20730 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
20740 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
20750 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
20760 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
20770 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
20780 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20790 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
207a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
207b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
207c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
207d0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
207e0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
207f0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
20800 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
20810 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
20820 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
20830 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
20840 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
20850 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20860 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
20870 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
20880 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
20890 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
208a0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
208b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
208c0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
208d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
208e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
208f0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
20900 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
20910 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
20920 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
20930 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
20940 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
20950 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
20960 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
20970 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
20980 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
20990 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
209a0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
209b0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
209c0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
209d0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
209e0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
209f0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
20a00 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
20a10 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
20a20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
20a30 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
20a40 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
20a50 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
20a60 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
20a70 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
20a80 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
20a90 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
20aa0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
20ab0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
20ac0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
20ad0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
20ae0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
20af0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
20b00 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
20b10 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
20b20 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
20b30 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
20b40 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
20b50 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
20b60 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
20b70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
20b80 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
20b90 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
20ba0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
20bb0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
20bc0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
20bd0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
20be0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
20bf0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
20c00 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
20c10 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
20c20 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
20c30 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
20c40 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
20c50 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
20c60 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
20c70 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
20c80 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
20c90 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
20ca0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
20cb0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
20cc0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
20cd0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
20ce0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
20cf0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
20d00 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
20d10 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
20d20 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
20d30 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
20d40 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
20d50 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
20d60 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
20d70 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20d80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
20d90 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
20da0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
20db0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
20dc0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
20dd0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
20de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20df0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
20e00 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
20e10 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
20e20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
20e30 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
20e40 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
20e50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20e60 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
20e70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
20e80 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
20e90 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
20ea0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
20eb0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
20ec0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20ed0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
20ee0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
20ef0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
20f00 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
20f10 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
20f20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
20f30 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
20f40 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
20f50 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
20f60 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
20f70 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
20f80 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
20f90 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
20fa0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
20fb0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
20fc0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
20fd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20fe0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
20ff0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
21000 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
21010 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
21020 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
21030 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
21040 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
21050 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
21060 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
21070 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
21080 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
21090 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
210a0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
210b0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
210c0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
210d0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
210e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
210f0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
21100 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
21110 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
21120 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
21130 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
21140 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
21150 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
21160 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
21170 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
21180 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
21190 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
211a0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
211b0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
211c0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
211d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
211e0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
211f0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
21200 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
21210 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
21220 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
21230 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
21240 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
21250 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
21260 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
21270 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
21280 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
21290 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
212a0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
212b0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
212c0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
212d0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
212e0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
212f0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
21300 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
21310 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
21320 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
21330 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
21340 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  uing..**.** ^[SQ
21350 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73  LITE_DONE] means
21360 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d   that the statem
21370 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64  ent has finished
21380 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75   executing.** su
21390 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c  ccessfully.  sql
213a0 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
213b0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
213c0 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76   again on this v
213d0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
213e0 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20  e without first 
213f0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
21400 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73  _reset()] to res
21410 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a  et the virtual.*
21420 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74  * machine back t
21430 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
21440 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ate..**.** ^If t
21450 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21460 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20   being executed 
21470 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61  returns any data
21480 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52  , then [SQLITE_R
21490 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  OW].** is return
214a0 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e  ed each time a n
214b0 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69  ew row of data i
214c0 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63  s ready for proc
214d0 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a  essing by the.**
214e0 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c   caller. The val
214f0 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73  ues may be acces
21500 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63  sed using the [c
21510 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
21520 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69  ctions]..** sqli
21530 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61  te3_step() is ca
21540 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65  lled again to re
21550 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20  trieve the next 
21560 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  row of data..**.
21570 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ** ^[SQLITE_ERRO
21580 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
21590 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
215a0 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
215b0 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
215c0 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
215d0 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
215e0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
215f0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
21600 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
21610 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
21620 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
21630 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
21640 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  sg()]..** ^With 
21650 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
21660 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65  face, a more spe
21670 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
21680 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (for example,.*
21690 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  * [SQLITE_INTERR
216a0 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43  UPT], [SQLITE_SC
216b0 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  HEMA], [SQLITE_C
216c0 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20  ORRUPT], and so 
216d0 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65  forth).** can be
216e0 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c   obtained by cal
216f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
21700 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a  set()] on the.**
21710 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21720 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20  ment].  ^In the 
21730 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
21740 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
21750 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
21760 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
21770 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
21780 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
21790 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
217a0 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
217b0 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
217c0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
217d0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
217e0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
217f0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
21800 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
21810 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
21820 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
21830 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
21840 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
21850 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
21860 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
21870 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
21880 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
21890 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
218a0 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
218b0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
218c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
218d0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
218e0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
218f0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
21900 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
21910 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
21920 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
21930 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
21940 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
21950 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
21960 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
21970 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
21980 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
21990 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
219a0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
219b0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
219c0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
219d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
219e0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
219f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21a00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
21a10 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
21a20 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
21a30 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
21a40 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
21a50 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
21a60 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
21a70 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
21a80 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
21a90 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
21aa0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
21ab0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
21ac0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
21ad0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
21ae0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
21af0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
21b00 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
21b10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21b20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
21b30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
21b40 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
21b50 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
21b60 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
21b70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
21b80 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
21b90 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
21ba0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
21bb0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
21bc0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
21bd0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
21be0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
21bf0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
21c00 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
21c10 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
21c20 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
21c30 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
21c40 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
21c50 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
21c60 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
21c70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
21c80 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 74  _data_count(P) t
21c90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
21ca0 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f  umns in the.** o
21cb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
21cc0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
21cd0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69  atement] P..*/.i
21ce0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
21cf0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
21d00 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
21d10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
21d20 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
21d30 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
21d40 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
21d50 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
21d60 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
21d70 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
21d80 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
21d90 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
21da0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
21db0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
21dc0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
21dd0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
21de0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
21df0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
21e00 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
21e10 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
21e20 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
21e30 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
21e40 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
21e50 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
21e60 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
21e70 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
21e80 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
21e90 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
21ea0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
21eb0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
21ec0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
21ed0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
21ee0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
21ef0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
21f00 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
21f10 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
21f20 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
21f30 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
21f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
21f50 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
21f60 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
21f70 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
21f80 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
21f90 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
21fa0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
21fb0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
21fc0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
21fd0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
21fe0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
21ff0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
22000 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
22010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22020 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
22030 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
22040 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
22050 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
22060 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
22070 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
22080 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
22090 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
220a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
220b0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
220c0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
220d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
220e0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
220f0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
22100 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
22110 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
22120 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
22130 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
22140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22150 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
22160 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
22170 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
22180 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
22190 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
221a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
221b0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
221c0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
221d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
221e0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
221f0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
22200 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
22210 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
22220 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
22230 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
22240 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
22250 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
22260 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
22270 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
22280 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
22290 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
222a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
222b0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
222c0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
222d0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
222e0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
222f0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
22300 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
22310 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
22320 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
22330 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
22340 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
22350 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
22360 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
22370 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
22380 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
22390 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
223a0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
223b0 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
223c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
223d0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
223e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
223f0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
22400 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
22410 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
22420 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
22430 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
22440 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
22450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
22460 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
22470 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
22480 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
22490 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
224a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
224b0 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
224c0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
224d0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
224e0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
224f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
22500 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22510 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
22520 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
22530 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
22540 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
22550 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
22560 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
22570 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
22580 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
22590 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
225a0 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
225b0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
225c0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
225d0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
225e0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
225f0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
22600 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
22610 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
22620 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
22630 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
22640 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
22650 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
22660 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
22670 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
22680 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
22690 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
226a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
226b0 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
226c0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
226d0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
226e0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
226f0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
22700 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
22710 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
22720 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
22730 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
22740 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
22750 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
22760 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
22770 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
22780 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
22790 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
227a0 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
227b0 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
227c0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
227d0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
227e0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
227f0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
22800 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
22810 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
22820 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
22830 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
22840 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
22850 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
22860 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
22870 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
22880 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
22890 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
228a0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
228b0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
228c0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
228d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
228e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
228f0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
22900 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
22910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22920 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
22930 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
22940 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
22950 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
22960 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
22970 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
22980 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
22990 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54  at string..** ^T
229a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
229b0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
229c0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
229d0 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e  inator at the en
229e0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
229f0 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
22a00 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
22a10 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
22a20 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
22a30 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
22a40 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
22a50 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
22a60 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
22a70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
22a80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
22a90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
22aa0 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
22ab0 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
22ac0 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
22ad0 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o terminated.  ^
22ae0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
22af0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
22b00 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
22b10 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
22b20 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69   BLOB is an arbi
22b30 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
22b40 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
22b50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
22b60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
22b70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
22b80 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  6() routine is s
22b90 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65  imilar to sqlite
22ba0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
22bb0 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74  .** but leaves t
22bc0 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46  he result in UTF
22bd0 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79  -16 in native by
22be0 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64  te order instead
22bf0 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54   of UTF-8..** ^T
22c00 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
22c10 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
22c20 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
22c30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
22c40 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
22c50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22c60 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
22c70 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
22c80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
22c90 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
22ca0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
22cb0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
22cc0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
22cd0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
22ce0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
22cf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
22d00 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
22d10 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
22d20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
22d30 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
22d40 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
22d50 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
22d60 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
22d70 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
22d80 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
22d90 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
22da0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
22db0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
22dc0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
22dd0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
22de0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
22df0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
22e00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
22e10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
22e20 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
22e30 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
22e40 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
22e50 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
22e60 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
22e70 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
22e80 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
22e90 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
22ea0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
22eb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
22ec0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
22ed0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
22ee0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
22ef0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
22f00 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
22f10 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
22f20 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
22f30 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
22f40 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
22f50 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
22f60 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
22f70 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
22f80 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
22f90 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
22fa0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
22fb0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
22fc0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
22fd0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
22fe0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
22ff0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
23000 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
23010 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
23020 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
23030 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
23040 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
23050 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
23060 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
23070 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
23080 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
23090 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
230a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
230b0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
230c0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
230d0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
230e0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
230f0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
23100 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
23110 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
23120 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
23130 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
23140 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
23150 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
23160 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
23170 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
23180 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
23190 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
231a0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
231b0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
231c0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
231d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
231e0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
231f0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
23200 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
23210 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
23220 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
23230 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
23240 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
23250 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
23260 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
23270 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
23280 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
23290 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
232a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
232b0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
232c0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
232d0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
232e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
232f0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
23300 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
23310 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
23320 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
23330 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
23340 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
23350 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
23360 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
23370 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
23380 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
23390 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
233a0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
233b0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
233c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
233d0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
233e0 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
233f0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
23400 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
23410 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
23420 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
23430 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
23440 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
23450 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
23460 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
23470 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
23480 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
23490 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
234a0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
234b0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
234c0 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
234d0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
234e0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
234f0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
23500 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
23510 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
23520 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
23530 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
23540 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
23550 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
23560 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
23570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
23580 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
23590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
235a0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
235b0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28  validated..** ^(
235c0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
235d0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
235e0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
235f0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
23600 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
23610 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
23620 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
23630 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
23640 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
23650 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
23660 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
23670 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
23680 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
23690 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
236a0 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
236b0 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
236c0 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
236d0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
236e0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
236f0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
23700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23710 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
23720 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
23730 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
23740 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
23750 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
23760 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
23770 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
23780 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
23790 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
237a0 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
237b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
237c0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
237d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
237e0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
237f0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
23800 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
23810 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
23820 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  /li>.** </ul>)^.
23830 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
23840 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
23850 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
23860 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
23870 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
23880 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
23890 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
238a0 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
238b0 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
238c0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
238d0 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
238e0 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
238f0 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
23900 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
23910 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
23920 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
23930 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
23940 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
23950 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
23960 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
23970 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
23980 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
23990 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
239a0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
239b0 20 5e 28 54 68 65 20 73 61 66 65 73 74 20 61 6e   ^(The safest an
239c0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
239d0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
239e0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
239f0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
23a00 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
23a10 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
23a20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
23a30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23a40 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
23a50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23a60 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
23a70 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
23a80 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
23a90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23aa0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
23ab0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
23ac0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
23ad0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
23ae0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
23af0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
23b00 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  ul>)^.**.** In o
23b10 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
23b20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
23b30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23b40 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
23b50 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
23b60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23b70 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
23b80 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
23b90 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
23ba0 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
23bb0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
23bc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23bd0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
23be0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
23bf0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
23c00 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
23c10 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
23c20 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
23c30 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
23c40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
23c50 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
23c60 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
23c70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
23c80 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
23c90 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
23ca0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
23cb0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
23cc0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
23cd0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
23ce0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
23cf0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
23d00 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
23d10 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
23d20 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
23d30 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
23d40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
23d50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
23d60 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
23d70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
23d80 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
23d90 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
23da0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
23db0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
23dc0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
23dd0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
23de0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
23df0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
23e00 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
23e10 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
23e20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
23e30 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
23e40 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
23e50 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
23e60 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
23e70 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
23e80 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
23e90 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
23ea0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
23eb0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
23ec0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
23ed0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
23ee0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
23ef0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
23f00 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
23f10 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
23f20 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
23f30 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
23f40 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
23f50 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
23f60 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
23f70 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
23f80 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
23f90 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23fa0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
23fb0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
23fc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
23fd0 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
23fe0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
23ff0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24000 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
24010 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24020 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
24030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
24040 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
24050 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
24060 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
24070 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
24080 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
24090 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
240a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
240b0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
240c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
240d0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
240e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
240f0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
24100 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
24110 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
24120 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
24130 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24140 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
24150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
24160 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
24170 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
24180 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
24190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
241a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
241b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
241c0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
241d0 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
241e0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
241f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24200 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
24210 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
24220 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
24230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24240 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 74  ]..** ^If the st
24250 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63  atement was exec
24260 75 74 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c  uted successfull
24270 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65  y or not execute
24280 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a  d at all, then.*
24290 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72  * SQLITE_OK is r
242a0 65 74 75 72 6e 65 64 2e 20 5e 49 66 20 65 78 65  eturned. ^If exe
242b0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  cution of the st
242c0 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20 74  atement failed t
242d0 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72  hen an.** [error
242e0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
242f0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
24300 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
24310 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
24320 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
24330 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
24340 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
24350 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   of the.** [prep
24360 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
24370 20 20 5e 49 66 20 74 68 65 20 76 69 72 74 75 61    ^If the virtua
24380 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f  l machine has no
24390 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  t.** completed e
243a0 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68  xecution when th
243b0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  is routine is ca
243c0 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69  lled, that is li
243d0 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69  ke.** encounteri
243e0 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61  ng an error or a
243f0 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  n [sqlite3_inter
24400 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74  rupt | interrupt
24410 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74  ]..** ^Incomplet
24420 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
24430 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
24440 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
24450 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e  nceled,.** depen
24460 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
24470 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
24480 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  he.** [error cod
24490 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
244a0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
244b0 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  T]..*/.int sqlit
244c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
244d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
244e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
244f0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
24500 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
24510 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ject.**.** The s
24520 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
24530 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
24540 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
24550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24560 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
24570 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
24580 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
24590 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
245a0 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74  ** ^Any SQL stat
245b0 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20  ement variables 
245c0 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20  that had values 
245d0 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73  bound to them us
245e0 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ing.** the [sqli
245f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
24600 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
24610 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65   API] retain the
24620 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73  ir values..** Us
24630 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  e [sqlite3_clear
24640 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20  _bindings()] to 
24650 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e  reset the bindin
24660 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  gs..**.** ^The [
24670 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
24680 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65  ] interface rese
24690 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  ts the [prepared
246a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a   statement] S.**
246b0 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
246c0 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
246d0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ogram..**.** ^If
246e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
246f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
24700 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
24710 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
24720 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
24730 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
24740 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
24750 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73  NE],.** or if [s
24760 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
24770 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
24780 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
24790 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69  S,.** then [sqli
247a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
247b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
247c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
247d0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
247e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
247f0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
24800 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24810 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74  ement] S indicat
24820 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65  ed an error, the
24830 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  n.** [sqlite3_re
24840 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
24850 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
24860 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
24870 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
24880 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
24890 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
248a0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
248b0 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74  ** of any [sqlit
248c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
248d0 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
248e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
248f0 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
24900 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
24910 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
24920 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24930 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
24940 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
24950 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
24960 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
24970 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
24980 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
24990 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
249a0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
249b0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
249c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
249d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
249e0 0a 2a 2a 20 5e 54 68 65 73 65 20 74 77 6f 20 66  .** ^These two f
249f0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
24a00 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
24a10 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
24a20 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
24a30 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
24a40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
24a50 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
24a60 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
24a70 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
24a80 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
24a90 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
24aa0 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
24ab0 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65  ifference betwee
24ac0 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20  n the.** two is 
24ad0 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
24ae0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e  parameter, the n
24af0 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c  ame of the (scal
24b00 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  ar) function or.
24b10 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73  ** aggregate, is
24b20 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
24b30 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  8 for sqlite3_cr
24b40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
24b50 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f  and UTF-16.** fo
24b60 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
24b70 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a  _function16()..*
24b80 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
24b90 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
24ba0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24bb0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
24bc0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
24bd0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
24be0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
24bf0 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
24c00 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
24c10 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
24c20 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
24c30 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
24c40 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
24c50 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
24c60 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
24c70 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
24c80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
24c90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
24ca0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
24cb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
24cc0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
24cd0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
24ce0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
24cf0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
24d00 74 6f 20 32 35 35 20 62 79 74 65 73 2c 20 65 78  to 255 bytes, ex
24d10 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68  clusive of.** th
24d20 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
24d30 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  r.  Note that th
24d40 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69  e name length li
24d50 6d 69 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c  mit is in bytes,
24d60 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65   not.** characte
24d70 72 73 2e 20 20 5e 41 6e 79 20 61 74 74 65 6d 70  rs.  ^Any attemp
24d80 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
24d90 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
24da0 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
24db0 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
24dc0 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67  ITE_ERROR] being
24dd0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
24de0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
24df0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
24e00 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
24e10 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
24e20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
24e30 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
24e40 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
24e50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
24e60 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
24e70 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
24e80 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
24e90 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
24ea0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
24eb0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
24ec0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
24ed0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
24ee0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
24ef0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
24f00 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
24f10 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
24f20 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
24f30 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
24f40 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
24f50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
24f60 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
24f70 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
24f80 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
24f90 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
24fa0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
24fb0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
24fc0 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
24fd0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
24fe0 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
24ff0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
25000 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
25010 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
25020 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
25030 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
25040 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
25050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
25060 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
25070 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
25080 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
25090 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70  nother.  ^An app
250a0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20  lication may.** 
250b0 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
250c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
250d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
250e0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20  te_function16() 
250f0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65  multiple.** time
25100 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
25110 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74  function but wit
25120 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75  h different valu
25130 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a  es of eTextRep..
25140 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
25150 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25160 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
25170 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
25180 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
25190 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
251a0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
251b0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
251c0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
251d0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
251e0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
251f0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25200 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
25210 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
25220 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
25230 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
25240 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
25250 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
25260 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  NY]..**.** ^(The
25270 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
25280 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
25290 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
252a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
252b0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
252c0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
252d0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
252e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
252f0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a  user_data()].)^.
25300 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74  **.** The sevent
25310 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
25320 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
25330 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
25340 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
25350 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
25360 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
25370 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
25380 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25390 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
253a0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
253b0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
253c0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
253d0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
253e0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
253f0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
25400 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
25410 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
25420 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
25430 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
25440 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
25450 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
25460 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
25470 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
25480 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 73  Final and NULL s
25490 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20  hould be passed 
254a0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
254b0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
254c0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
254d0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
254e0 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61 6c  pass NULL for al
254f0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
25500 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
25510 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
25520 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
25530 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
25540 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
25550 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
25560 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
25570 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
25580 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
25590 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
255a0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
255b0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
255c0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
255d0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
255e0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
255f0 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
25600 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
25610 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
25620 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
25630 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
25640 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
25650 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
25660 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
25670 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
25680 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
25690 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
256a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
256b0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
256c0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
256d0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
256e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
256f0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
25700 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
25710 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
25720 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
25730 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
25740 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
25750 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
25760 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
25770 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
25780 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
25790 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
257a0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
257b0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
257c0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
257d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
257e0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
257f0 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
25800 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
25810 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
25820 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
25830 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
25840 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
25850 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
25860 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 70  ** ^The first ap
25870 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
25880 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  d function with 
25890 61 20 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65  a given name ove
258a0 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75  rrides all.** bu
258b0 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
258c0 20 69 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   in the same [da
258d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
258e0 6e 5d 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  n] with the same
258f0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75 62 73 65   name..** ^Subse
25900 71 75 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f  quent applicatio
25910 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
25920 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
25930 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69  name only overri
25940 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70  de .** prior app
25950 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25960 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
25970 61 72 65 20 61 6e 20 65 78 61 63 74 20 6d 61 74  are an exact mat
25980 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75  ch for the.** nu
25990 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
259a0 72 73 20 61 6e 64 20 70 72 65 66 65 72 72 65 64  rs and preferred
259b0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
259c0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
259d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
259e0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
259f0 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
25a00 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
25a10 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
25a20 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
25a30 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
25a40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25a50 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
25a60 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
25a70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
25a80 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
25a90 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
25aa0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
25ab0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25ac0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
25ad0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
25ae0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
25af0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
25b00 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
25b10 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
25b20 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
25b30 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
25b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
25b50 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
25b60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25b70 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
25b80 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
25b90 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
25ba0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
25bb0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
25bc0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
25bd0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
25be0 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
25bf0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
25c00 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
25c10 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
25c20 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
25c30 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
25c40 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
25c50 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
25c60 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
25c70 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
25c80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
25c90 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
25ca0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
25cb0 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t*).);../*.** CA
25cc0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
25cd0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
25ce0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
25cf0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
25d00 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
25d10 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
25d20 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
25d30 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
25d40 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
25d50 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
25d60 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
25d70 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
25d80 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
25d90 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
25da0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
25db0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
25dc0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
25dd0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
25de0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
25df0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
25e00 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
25e10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25e20 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
25e30 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
25e40 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
25e50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
25e60 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
25e70 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
25e80 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
25e90 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
25ea0 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
25eb0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
25ec0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
25ed0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
25ee0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
25ef0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
25f00 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
25f10 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
25f20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
25f30 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
25f40 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
25f50 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
25f60 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
25f70 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
25f80 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
25f90 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
25fa0 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
25fb0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
25fc0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
25fd0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
25fe0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
25ff0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
26000 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
26010 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
26020 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
26030 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
26040 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
26050 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
26060 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
26070 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
26080 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
26090 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
260a0 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
260b0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
260c0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
260d0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
260e0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
260f0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
26100 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
26110 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
26120 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
26130 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
26140 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
26150 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
26160 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
26170 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
26180 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
26190 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
261a0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
261b0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
261c0 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
261d0 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
261e0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
261f0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
26200 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
26210 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
26220 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
26230 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
26240 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
26250 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
26260 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
26270 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
26280 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
26290 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
262a0 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
262b0 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
262c0 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
262d0 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
262e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
262f0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
26300 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26310 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
26320 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
26330 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
26340 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
26350 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
26360 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61 6d  ** The 4th param
26370 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
26380 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
26390 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
263a0 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
263b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
263c0 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
263d0 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
263e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
263f0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
26400 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
26410 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
26420 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
26430 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
26440 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
26450 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
26460 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
26470 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
26480 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
26490 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
264a0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
264b0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
264c0 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
264d0 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
264e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
264f0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
26500 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
26510 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
26520 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
26530 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
26540 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
26550 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
26560 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
26570 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
26580 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
26590 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
265a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
265b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
265c0 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
265d0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
265e0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
265f0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
26600 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
26610 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26620 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
26630 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
26640 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
26650 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
26660 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
26670 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
26680 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
26690 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
266a0 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
266b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
266c0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
266d0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
266e0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
266f0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
26700 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
26710 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
26720 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
26730 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
26740 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
26750 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
26760 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
26770 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
26780 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
26790 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
267a0 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
267b0 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
267c0 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
267d0 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
267e0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
267f0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
26800 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
26810 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
26820 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
26830 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
26840 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
26850 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
26860 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
26870 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
26880 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
26890 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
268a0 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
268b0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
268c0 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
268d0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
268e0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
268f0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
26900 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
26910 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
26920 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
26930 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
26940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
26950 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
26960 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
26970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
26980 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
26990 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
269a0 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
269b0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
269c0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
269d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
269e0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
269f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
26a00 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
26a10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26a20 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
26a30 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
26a40 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
26a50 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
26a60 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
26a70 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
26a80 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
26a90 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
26aa0 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
26ab0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
26ac0 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
26ad0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
26ae0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
26af0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26b00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
26b10 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
26b20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
26b30 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
26b40 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
26b50 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
26b60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
26b70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26b80 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
26b90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
26ba0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
26bb0 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
26bc0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
26bd0 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
26be0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
26bf0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26c00 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
26c10 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
26c20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
26c30 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
26c40 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
26c50 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
26c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26c70 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
26c80 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26c90 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
26ca0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
26cb0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
26cc0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
26cd0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
26ce0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26cf0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
26d00 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
26d10 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
26d20 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
26d30 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
26d40 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
26d50 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
26d60 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
26d70 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
26d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
26d90 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
26da0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
26db0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
26dc0 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
26dd0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
26de0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
26df0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
26e00 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
26e10 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
26e20 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
26e30 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
26e40 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
26e50 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
26e60 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
26e70 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
26e80 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
26e90 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
26ea0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
26eb0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
26ec0 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
26ed0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
26ee0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
26ef0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
26f00 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
26f10 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
26f20 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
26f30 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
26f40 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
26f50 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
26f60 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
26f70 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
26f80 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
26f90 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
26fa0 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
26fb0 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
26fc0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
26fd0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
26fe0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
26ff0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
27000 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
27010 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
27020 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
27030 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
27040 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27050 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
27060 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
27070 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
27080 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
27090 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
270a0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
270b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
270c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
270d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
270e0 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20  if N is.** less 
270f0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
27100 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65   zero or if a me
27110 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72  mory allocate er
27120 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
27130 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
27140 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
27150 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
27160 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
27170 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
27180 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
27190 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
271a0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
271b0 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
271c0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
271d0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
271e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
271f0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
27200 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
27210 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
27220 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
27230 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
27240 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
27250 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  ocation.)^.**.**
27260 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74   ^SQLite automat
27270 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65  ically frees the
27280 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
27290 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
272a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
272b0 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67  xt() when the ag
272c0 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f  gregate query co
272d0 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  ncludes..**.** T
272e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
272f0 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70  er must be a cop
27300 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  y of the.** [sql
27310 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53  ite3_context | S
27320 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74  QL function cont
27330 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65  ext] that is the
27340 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
27350 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70  .** to the xStep
27360 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
27370 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74  ack routine that
27380 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
27390 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e  aggregate.** fun
273a0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
273b0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
273c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
273d0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
273e0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67   which.** the ag
273f0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
27400 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
27410 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
27420 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
27430 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
27440 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73  ext*, int nBytes
27450 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27460 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f  EF: User Data Fo
27470 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  r Functions.**.*
27480 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
27490 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
274a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
274b0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
274c0 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
274d0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
274e0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
274f0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
27500 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
27510 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
27520 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
27530 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
27540 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
27550 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
27560 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
27570 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
27580 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
27590 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
275a0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
275b0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
275c0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
275d0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
275e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
275f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
27600 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
27610 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
27620 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
27630 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
27640 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
27650 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
27660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27670 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
27680 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  ndle() interface
27690 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
276a0 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
276b0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
276c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
276d0 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
276e0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
276f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
27700 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
27710 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27720 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
27730 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
27740 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
27750 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
27760 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
27770 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ction..*/.sqlite
27780 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
27790 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
277a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
277b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
277c0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
277d0 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
277e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
277f0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
27800 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
27810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
27820 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
27830 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
27840 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
27850 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
27860 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
27870 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
27880 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
27890 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
278a0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
278b0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
278c0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
278d0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
278e0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
278f0 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
27900 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
27910 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
27920 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
27930 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
27940 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
27950 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
27960 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
27970 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
27980 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
27990 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
279a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
279b0 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
279c0 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
279d0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
279e0 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
279f0 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
27a00 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
27a10 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
27a20 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
27a30 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
27a40 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
27a50 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
27a60 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
27a70 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27a80 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
27a90 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
27aa0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
27ab0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
27ac0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
27ad0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
27ae0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
27af0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
27b00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
27b10 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
27b20 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
27b30 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
27b40 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
27b50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
27b60 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d  nction. ^If no m
27b70 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
27b80 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
27b90 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
27ba0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
27bb0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
27bc0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
27bd0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
27be0 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
27bf0 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
27c00 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
27c10 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
27c20 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
27c30 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
27c40 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
27c50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
27c60 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
27c70 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
27c80 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
27c90 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
27ca0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
27cb0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
27cc0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
27cd0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
27ce0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
27cf0 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
27d00 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
27d10 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
27d20 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
27d30 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
27d40 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
27d50 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49  destroyed..** ^I
27d60 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
27d70 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
27d80 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
27d90 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
27da0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
27db0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
27dc0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
27dd0 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
27de0 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
27df0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
27e00 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
27e10 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
27e20 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
27e30 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
27e40 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
27e50 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
27e60 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
27e70 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
27e80 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
27e90 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
27ea0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
27eb0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
27ec0 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c   time.  ^The onl
27ed0 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
27ee0 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
27ef0 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
27f00 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
27f10 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
27f20 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ped..**.** ^(In 
27f30 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
27f40 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
27f50 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
27f60 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
27f70 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
27f80 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
27f90 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
27fa0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
27fb0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
27fc0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e   [parameters].)^
27fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
27fe0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
27ff0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
28000 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
28010 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
28020 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
28030 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
28040 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
28050 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
28060 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
28070 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
28080 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
28090 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
280a0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
280b0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
280c0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
280d0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
280e0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
280f0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
28100 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
28110 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
28120 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
28130 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
28140 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
28150 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
28160 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
28170 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
28180 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
28190 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
281a0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
281b0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
281c0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
281d0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
281e0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
281f0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
28200 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
28210 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
28220 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
28230 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
28240 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
28250 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
28260 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
28270 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
28280 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
28290 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
282a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
282b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
282c0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
282d0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
282e0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
282f0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
28300 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
28310 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
28320 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
28330 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
28340 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
28350 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
28360 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
28370 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
28380 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
28390 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
283a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
283b0 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
283c0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
283d0 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
283e0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
283f0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
28400 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
28410 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
28420 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
28430 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
28440 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
28450 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
28460 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
28470 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
28480 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
28490 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
284a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
284b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
284c0 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
284d0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
284e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
284f0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
28500 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
28510 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
28520 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
28530 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
28540 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
28550 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
28560 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
28570 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
28580 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
28590 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
285a0 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
285b0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
285c0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
285d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
285e0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
285f0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
28600 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
28610 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28620 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
28630 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
28640 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
28650 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
28660 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
28670 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
28680 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
28690 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
286a0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
286b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
286c0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
286d0 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
286e0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
286f0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
28700 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
28710 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
28720 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
28730 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
28740 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
28750 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
28760 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
28770 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
28780 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28790 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
287a0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
287b0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
287c0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
287d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
287e0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
287f0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
28800 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
28810 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
28820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28830 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
28840 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
28850 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
28860 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
28870 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
28880 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
28890 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
288a0 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
288b0 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
288c0 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
288d0 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
288e0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
288f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
28900 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
28910 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
28920 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
28930 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
28940 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
28950 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
28960 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
28970 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
28980 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
28990 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
289a0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
289b0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
289c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
289d0 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
289e0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
289f0 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
28a00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28a10 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
28a20 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
28a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
28a40 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
28a50 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
28a60 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
28a70 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
28a80 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
28a90 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
28aa0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
28ab0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
28ac0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
28ad0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
28ae0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
28af0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
28b00 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
28b10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
28b20 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
28b30 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
28b40 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
28b50 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
28b60 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
28b70 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
28b80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
28b90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
28ba0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
28bb0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
28bc0 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
28bd0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
28be0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
28bf0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
28c00 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
28c10 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
28c20 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
28c30 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
28c40 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
28c50 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
28c60 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
28c70 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
28c80 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
28c90 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
28ca0 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
28cb0 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
28cc0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
28cd0 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
28ce0 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
28cf0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
28d00 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
28d10 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
28d20 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
28d30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
28d40 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
28d50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
28d60 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
28d70 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
28d80 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
28d90 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
28da0 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
28db0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
28dc0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
28dd0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
28de0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
28df0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
28e00 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
28e10 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
28e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
28e30 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
28e40 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
28e50 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
28e60 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
28e70 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
28e80 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
28e90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28ea0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
28eb0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
28ec0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
28ed0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
28ee0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28ef0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
28f00 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
28f10 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
28f20 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
28f30 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
28f40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28f50 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
28f60 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
28f70 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
28f80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
28f90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
28fa0 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
28fb0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
28fc0 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
28fd0 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
28fe0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
28ff0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
29000 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
29010 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
29020 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
29030 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
29040 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
29050 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
29060 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29070 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
29080 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
29090 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
290a0 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
290b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
290c0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
290d0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
290e0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
290f0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
29100 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29110 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
29120 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
29130 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
29140 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
29150 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
29160 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
29170 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
29180 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
29190 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
291a0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
291b0 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
291c0 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
291d0 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
291e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
291f0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
29200 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
29210 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
29220 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
29230 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
29240 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
29250 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
29260 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
29270 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
29280 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
29290 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
292a0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
292b0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
292c0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
292d0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
292e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
292f0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
29300 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
29310 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
29320 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
29330 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
29340 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
29350 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
29360 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
29370 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
29380 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29390 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
293a0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
293b0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
293c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
293d0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
293e0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
293f0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
29400 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
29410 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
29420 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
29430 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
29440 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
29450 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
29460 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
29470 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
29480 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
29490 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
294a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
294b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
294c0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
294d0 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
294e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
294f0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
29500 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
29510 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
29520 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
29530 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
29540 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
29550 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
29560 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
29570 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
29580 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
29590 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
295a0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
295b0 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
295c0 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
295d0 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
295e0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
295f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
29600 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29610 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
29620 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
29630 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
29640 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
29650 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
29660 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
29670 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
29680 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
29690 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
296a0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
296b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
296c0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
296d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
296e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
296f0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
29700 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
29710 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
29720 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29730 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
29740 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
29750 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29760 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
29770 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
29780 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
29790 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
297a0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
297b0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
297c0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
297d0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
297e0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
297f0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
29800 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
29810 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
29820 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
29830 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
29840 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
29850 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
29860 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
29870 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29880 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
29890 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
298a0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
298b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
298c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
298d0 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
298e0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
298f0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
29900 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
29910 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
29920 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
29930 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
29940 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
29950 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
29960 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
29970 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
29980 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
29990 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
299a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
299b0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
299c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
299d0 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
299e0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
299f0 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
29a00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
29a10 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
29a20 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
29a30 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
29a40 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
29a50 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
29a60 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
29a70 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
29a80 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
29a90 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
29aa0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
29ab0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
29ac0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
29ad0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
29ae0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
29af0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
29b00 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
29b10 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
29b20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
29b30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29b40 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
29b50 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
29b60 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
29b70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
29b80 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
29b90 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
29ba0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29bb0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
29bc0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
29bd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29be0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
29bf0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
29c00 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
29c10 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
29c20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29c30 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
29c40 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
29c50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29c60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
29c70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
29c80 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29c90 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
29ca0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
29cb0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
29cc0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
29cd0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
29ce0 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
29cf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29d00 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
29d10 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
29d20 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29d30 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
29d40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29d50 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29d60 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
29d70 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
29d80 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
29d90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
29db0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
29dc0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
29dd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
29de0 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
29df0 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
29e00 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
29e10 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 54 68  quences.**.** Th
29e20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
29e30 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65  e used to add ne
29e40 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
29e50 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  ences to the.** 
29e60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29e70 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
29e80 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
29e90 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
29ea0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65  e name of the ne
29eb0 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  w collation sequ
29ec0 65 6e 63 65 20 69 73 20 73 70 65 63 69 66 69 65  ence is specifie
29ed0 64 20 61 73 20 61 20 55 54 46 2d 38 20 73 74 72  d as a UTF-8 str
29ee0 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74  ing.** for sqlit
29ef0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
29f00 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ion() and sqlite
29f10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29f20 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61  on_v2().** and a
29f30 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66   UTF-16 string f
29f40 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
29f50 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
29f60 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a   ^In all cases.*
29f70 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20 70 61  * the name is pa
29f80 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
29f90 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
29fa0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
29fb0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
29fc0 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  may be one of th
29fd0 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c  e constants [SQL
29fe0 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53  ITE_UTF8],.** [S
29ff0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
2a000 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2a010 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  BE], indicating 
2a020 74 68 61 74 20 74 68 65 20 75 73 65 72 2d 73 75  that the user-su
2a030 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74 69 6e  pplied.** routin
2a040 65 20 65 78 70 65 63 74 73 20 74 6f 20 62 65 20  e expects to be 
2a050 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72 73 20  passed pointers 
2a060 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63 6f 64  to strings encod
2a070 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 2c 0a  ed using UTF-8,.
2a080 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2a090 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d  -endian, or UTF-
2a0a0 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c 20 72  16 big-endian, r
2a0b0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e 54 68  espectively. ^Th
2a0c0 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67 75 6d  e.** third argum
2a0d0 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f 20 62  ent might also b
2a0e0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
2a0f0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
2a100 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a 2a 2a  t the routine.**
2a110 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
2a120 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36 20 73  s to be UTF-16 s
2a130 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 6e 61  trings in the na
2a140 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
2a150 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   or the.** argum
2a160 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51 4c 49  ent can be [SQLI
2a170 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2a180 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68 65 20  ] if the.** the 
2a190 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
2a1a0 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36 2d 62  pointers to 16-b
2a1b0 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65 64 20  it word aligned 
2a1c0 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20 55 54  strings.** of UT
2a1d0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
2a1e0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2a1f0 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
2a200 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
2a210 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
2a220 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2a230 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
2a240 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ent.  ^If it is 
2a250 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68  NULL, this is th
2a260 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69  e same as deleti
2a270 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ng the collation
2a280 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f  .** sequence (so
2a290 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
2a2a0 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d  not call it anym
2a2b0 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 74  ore)..** ^Each t
2a2c0 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61 74  ime the applicat
2a2d0 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e  ion supplied fun
2a2e0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
2a2f0 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a  , it is passed.*
2a300 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20 70  * as its first p
2a310 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20  arameter a copy 
2a320 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73  of the void* pas
2a330 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
2a340 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
2a350 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a360 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73  collation() or s
2a370 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a380 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  llation16()..**.
2a390 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e 69 6e  ** ^The remainin
2a3a0 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  g arguments to t
2a3b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  he application-s
2a3c0 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
2a3d0 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c  are two strings,
2a3e0 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65  .** each represe
2a3f0 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74  nted by a (lengt
2a400 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e  h, data) pair an
2a410 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65  d encoded in the
2a420 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61   encoding.** tha
2a430 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20  t was passed as 
2a440 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
2a450 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  nt when the coll
2a460 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77  ation sequence w
2a470 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  as.** registered
2a480 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
2a490 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61  on defined colla
2a4a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f  tion routine sho
2a4b0 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65  uld.** return ne
2a4c0 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20  gative, zero or 
2a4d0 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65 20  positive if the 
2a4e0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
2a4f0 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71  less than,.** eq
2a500 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
2a510 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
2a520 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20  nd string. i.e. 
2a530 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e  (STRING1 - STRIN
2a540 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  G2)..**.** ^The 
2a550 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a560 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
2a570 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
2a580 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a590 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
2a5a0 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
2a5b0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
2a5c0 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
2a5d0 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
2a5e0 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20  ollation.  ^The 
2a5f0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2a600 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f  lled when the co
2a610 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  llation is.** de
2a620 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70  stroyed and is p
2a630 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20  assed a copy of 
2a640 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2a650 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74  eter void* point
2a660 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  er.** of the sql
2a670 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a680 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 5e  ation_v2()..** ^
2a690 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
2a6a0 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68  estroyed when th
2a6b0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
2a6c0 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
2a6d0 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61   to the.** colla
2a6e0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
2a6f0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
2a700 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2a710 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
2a720 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  sed.** using [sq
2a730 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
2a740 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2a750 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
2a760 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
2a770 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
2a780 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
2a790 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a7a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a7b0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
2a7c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2a7d0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2a7e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2a7f0 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2a800 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2a810 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2a820 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
2a830 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a840 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
2a850 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2a860 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2a870 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2a880 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
2a890 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
2a8a0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
2a8b0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
2a8c0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
2a8d0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
2a8e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2a8f0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
2a900 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2a910 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
2a920 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
2a930 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
2a940 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
2a950 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2a960 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
2a970 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
2a980 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
2a990 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
2a9a0 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64  .**.** ^To avoid
2a9b0 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73   having to regis
2a9c0 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f  ter all collatio
2a9d0 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f  n sequences befo
2a9e0 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  re a database.**
2a9f0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20   can be used, a 
2aa00 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20  single callback 
2aa10 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20  function may be 
2aa20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20  registered with 
2aa30 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2aa40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2aa50 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2aa60 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
2aa70 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2aa80 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
2aa90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
2aaa0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
2aab0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
2aac0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
2aad0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
2aae0 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
2aaf0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
2ab00 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
2ab10 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2ab20 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
2ab30 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
2ab40 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  8. ^If sqlite3_c
2ab50 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2ab60 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20  6() is used,.** 
2ab70 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61  the names are pa
2ab80 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  ssed as UTF-16 i
2ab90 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65  n machine native
2aba0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
2abb0 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ^A call to eithe
2abc0 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61  r function repla
2abd0 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67  ces the existing
2abe0 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65   collation-neede
2abf0 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  d callback..**.*
2ac00 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c  * ^(When the cal
2ac10 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2ac20 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  , the first argu
2ac30 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61  ment passed is a
2ac40 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
2ac50 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2ac60 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  to sqlite3_colla
2ac70 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72  tion_needed() or
2ac80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  .** sqlite3_coll
2ac90 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
2aca0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  .  The second ar
2acb0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61  gument is the da
2acc0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2acd0 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64  tion.  The third
2ace0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
2acf0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   of [SQLITE_UTF8
2ad00 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2ad10 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  BE],.** or [SQLI
2ad20 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64  TE_UTF16LE], ind
2ad30 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74  icating the most
2ad40 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20   desirable form 
2ad50 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
2ad60 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e  .** sequence fun
2ad70 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20  ction required. 
2ad80 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
2ad90 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2ada0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75  e of the.** requ
2adb0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ired collation s
2adc0 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  equence.)^.**.**
2add0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
2ade0 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65  nction should re
2adf0 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72  gister the desir
2ae00 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69  ed collation usi
2ae10 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2ae20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2ae30 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2ae40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2ae50 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2ae60 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2ae70 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e  ion_v2()]..*/.in
2ae80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
2ae90 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
2aea0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
2aeb0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
2aec0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2aed0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
2aee0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
2aef0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2af00 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
2af10 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
2af20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
2af30 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
2af40 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
2af50 29 0a 29 3b 0a 0a 23 69 66 20 53 51 4c 49 54 45  ).);..#if SQLITE
2af60 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
2af70 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2af80 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2af90 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2afa0 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2afb0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2afc0 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2afd0 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2afe0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2aff0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2b000 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2b010 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2b020 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2b030 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2b040 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2b050 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2b060 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2b070 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2b080 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2b090 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2b0a0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2b0b0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2b0c0 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2b0d0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2b0e0 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2b0f0 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2b100 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2b110 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2b120 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2b130 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2b140 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2b150 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2b160 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2b170 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2b180 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2b190 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2b1a0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2b1b0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2b1c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2b1d0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2b1e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2b1f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2b200 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2b210 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2b220 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2b230 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2b240 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2b250 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
2b260 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
2b270 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
2b280 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
2b290 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
2b2a0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
2b2b0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
2b2c0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
2b2d0 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
2b2e0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2b2f0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2b300 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2b310 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
2b320 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
2b330 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
2b340 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2b350 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
2b360 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
2b370 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
2b380 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
2b390 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
2b3a0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
2b3b0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2b3c0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
2b3d0 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
2b3e0 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
2b3f0 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
2b400 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
2b410 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2b420 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
2b430 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
2b440 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
2b450 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
2b460 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
2b470 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
2b480 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
2b490 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
2b4a0 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
2b4b0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
2b4c0 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
2b4d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2b4e0 5e 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e  ^If the operatin
2b4f0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
2b500 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
2b510 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
2b520 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
2b530 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
2b540 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
2b550 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
2b560 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
2b570 20 73 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75   second. ^The nu
2b580 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2b590 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
2b5a0 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
2b5b0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
2b5c0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
2b5d0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2b5e0 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
2b5f0 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
2b600 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
2b610 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
2b620 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
2b630 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
2b640 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74  ] object..*/.int
2b650 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
2b660 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2b670 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
2b680 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
2b690 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
2b6a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73  .**.** ^(If this
2b6b0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
2b6c0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2b6d0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
2b6e0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
2b6f0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
2b700 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
2b710 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
2b720 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
2b730 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
2b740 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75   when using a bu
2b750 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ilt-in [sqlite3_
2b760 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69  vfs | VFS].** wi
2b770 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
2b780 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29  that directory.)
2b790 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69  ^  ^If this vari
2b7a0 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
2b7b0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
2b7c0 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
2b7d0 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
2b7e0 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
2b7f0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
2b800 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
2b810 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
2b820 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
2b830 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
2b840 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
2b850 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
2b860 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
2b870 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
2b880 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
2b890 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
2b8a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b8b0 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
2b8c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
2b8d0 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
2b8e0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
2b8f0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
2b900 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
2b910 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
2b920 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
2b930 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
2b940 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
2b950 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
2b960 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
2b970 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
2b980 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
2b990 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
2b9a0 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
2b9b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
2b9c0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2b9d0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
2b9e0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2b9f0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
2ba00 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
2ba10 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
2ba20 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2ba30 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
2ba40 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
2ba50 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2ba60 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
2ba70 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
2ba80 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
2ba90 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2baa0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
2bab0 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
2bac0 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
2bad0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2bae0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
2baf0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
2bb00 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
2bb10 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2bb20 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
2bb30 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
2bb40 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
2bb50 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
2bb60 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
2bb70 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
2bb80 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
2bb90 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2bba0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2bbb0 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
2bbc0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
2bbd0 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
2bbe0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
2bbf0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2bc00 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
2bc10 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74   char *sqlite3_t
2bc20 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a  emp_directory;..
2bc30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2bc40 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f  Test For Auto-Co
2bc50 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59  mmit Mode.** KEY
2bc60 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
2bc70 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e  it mode}.**.** ^
2bc80 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
2bc90 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74  autocommit() int
2bca0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
2bcb0 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65  on-zero or.** ze
2bcc0 72 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20  ro if the given 
2bcd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bce0 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74  ion is or is not
2bcf0 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d   in autocommit m
2bd00 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ode,.** respecti
2bd10 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d  vely.  ^Autocomm
2bd20 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79  it mode is on by
2bd30 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75   default..** ^Au
2bd40 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2bd50 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
2bd60 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
2bd70 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
2bd80 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62   mode is re-enab
2bd90 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54  led by a [COMMIT
2bda0 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e  ] or [ROLLBACK].
2bdb0 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69  .**.** If certai
2bdc0 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72  n kinds of error
2bdd0 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61  s occur on a sta
2bde0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
2bdf0 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a  multi-statement.
2be00 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28  ** transaction (
2be10 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67  errors including
2be20 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20   [SQLITE_FULL], 
2be30 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a  [SQLITE_IOERR],.
2be40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2be50 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
2be60 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e  , and [SQLITE_IN
2be70 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74  TERRUPT]) then t
2be80 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  he.** transactio
2be90 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65  n might be rolle
2bea0 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
2beb0 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ally.  The only 
2bec0 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f  way to.** find o
2bed0 75 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74  ut whether SQLit
2bee0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2bef0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20  rolled back the 
2bf00 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65  transaction afte
2bf10 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73  r.** an error is
2bf20 20 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e   to use this fun
2bf30 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
2bf40 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63  another thread c
2bf50 68 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63  hanges the autoc
2bf60 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20  ommit status of 
2bf70 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2bf80 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
2bf90 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
2bfa0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
2bfb0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
2bfc0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2bfd0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2bfe0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73  get_autocommit(s
2bff0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
2c000 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2c010 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e  The Database Han
2c020 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65  dle Of A Prepare
2c030 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2c040 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2c050 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61  b_handle interfa
2c060 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
2c070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c080 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74  ion] handle.** t
2c090 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61  o which a [prepa
2c0a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62  red statement] b
2c0b0 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64  elongs.  ^The [d
2c0c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c0d0 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  on].** returned 
2c0e0 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  by sqlite3_db_ha
2c0f0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
2c100 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c110 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77  ction].** that w
2c120 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
2c130 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
2c140 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c150 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20  _v2()] call (or 
2c160 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68  its variants) th
2c170 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a  at was used to.*
2c180 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61  * create the sta
2c190 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69  tement in the fi
2c1a0 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71  rst place..*/.sq
2c1b0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
2c1c0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
2c1d0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2c1e0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
2c1f0 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
2c200 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
2c210 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
2c220 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c230 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
2c240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c250 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
2c260 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
2c270 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
2c280 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
2c290 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20  .  ^If pStmt is 
2c2a0 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
2c2b0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
2c2c0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2c2d0 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
2c2e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2c2f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2c310 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e  nnection pDb.  ^
2c320 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
2c330 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
2c340 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
2c350 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
2c360 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
2c370 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
2c380 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c390 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
2c3a0 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
2c3b0 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2c3c0 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
2c3d0 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
2c3e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2c3f0 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
2c400 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
2c410 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
2c420 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ter..*/.sqlite3_
2c430 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
2c440 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
2c450 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
2c460 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2c470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2c480 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
2c490 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
2c4a0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
2c4b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
2c4c0 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
2c4d0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
2c4e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
2c4f0 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
2c500 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
2c510 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d  nsaction is [COM
2c520 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d  MIT | committed]
2c530 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
2c540 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2c550 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
2c560 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2c570 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2c580 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2c590 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2c5a0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  dden..** ^The sq
2c5b0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2c5c0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2c5d0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2c5e0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2c5f0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2c600 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2c610 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
2c620 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
2c630 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
2c640 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2c650 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2c660 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
2c670 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
2c680 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
2c690 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
2c6a0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
2c6b0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
2c6c0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
2c6d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2c6e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
2c6f0 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
2c700 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
2c710 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2c720 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
2c730 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
2c740 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
2c750 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  k..**.** ^The sq
2c760 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2c770 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c  k(D,C,P) and sql
2c780 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
2c790 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
2c7a0 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ons.** return th
2c7b0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
2c7c0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
2c7d0 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20  all of the same 
2c7e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74  function.** on t
2c7f0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2c800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
2c810 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
2c820 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
2c830 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e  or each function
2c840 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on D..**.** The
2c850 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d   callback implem
2c860 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  entation must no
2c870 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
2c880 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
2c890 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
2c8a0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
2c8b0 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62  nvoked the callb
2c8c0 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e  ack.  Any action
2c8d0 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74  s.** to modify t
2c8e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c8f0 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64  ection must be d
2c900 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66  eferred until af
2c910 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  ter the.** compl
2c920 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71  etion of the [sq
2c930 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
2c940 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
2c950 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20  d the commit.** 
2c960 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  or rollback hook
2c970 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
2c980 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ace..** Note tha
2c990 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
2c9a0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2c9b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
2c9c0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
2c9d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
2c9e0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
2c9f0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
2ca00 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
2ca10 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  graph..**.** ^Re
2ca20 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c  gistering a NULL
2ca30 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
2ca40 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  es the callback.
2ca50 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  .**.** ^When the
2ca60 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c   commit hook cal
2ca70 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
2ca80 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20  turns zero, the 
2ca90 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72  [COMMIT].** oper
2caa0 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64  ation is allowed
2cab0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72   to continue nor
2cac0 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20  mally.  ^If the 
2cad0 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72  commit hook.** r
2cae0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
2caf0 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49   then the [COMMI
2cb00 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  T] is converted 
2cb10 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b  into a [ROLLBACK
2cb20 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  ]..** ^The rollb
2cb30 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f  ack hook is invo
2cb40 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63  ked on a rollbac
2cb50 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66  k that results f
2cb60 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20  rom a commit.** 
2cb70 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e  hook returning n
2cb80 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73  on-zero, just as
2cb90 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74   it would be wit
2cba0 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c  h any other roll
2cbb0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  back..**.** ^For
2cbc0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
2cbd0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
2cbe0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
2cbf0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
2cc00 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
2cc10 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
2cc20 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
2cc30 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
2cc40 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
2cc50 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
2cc60 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
2cc70 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
2cc80 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63  .** ^The rollbac
2cc90 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f  k callback is no
2cca0 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74  t invoked if a t
2ccb0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a  ransaction is.**
2ccc0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2ccd0 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75  olled back becau
2cce0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
2ccf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
2cd00 6f 73 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  osed..** ^The ro
2cd10 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20  llback callback 
2cd20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69  is not invoked i
2cd30 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  f a transaction 
2cd40 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  is.** rolled bac
2cd50 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d  k because a comm
2cd60 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  it callback retu
2cd70 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a  rned non-zero..*
2cd80 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
2cd90 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
2cda0 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
2cdb0 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
2cdc0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2cdd0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
2cde0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
2cdf0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
2ce00 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
2ce10 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
2ce20 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
2ce30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2ce40 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
2ce50 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
2ce60 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
2ce70 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
2ce80 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2ce90 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2cea0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
2ceb0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2cec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2ced0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2cee0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2cef0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
2cf00 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
2cf10 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
2cf20 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
2cf30 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
2cf40 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2cf50 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
2cf60 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
2cf70 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
2cf80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2cf90 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
2cfa0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2cfb0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
2cfc0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
2cfd0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
2cfe0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
2cff0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2d000 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2d010 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2d020 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
2d030 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
2d040 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
2d050 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
2d060 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
2d070 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
2d080 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
2d090 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2d0a0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
2d0b0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
2d0c0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2d0d0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
2d0e0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2d0f0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2d100 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
2d110 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
2d120 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2d130 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
2d140 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
2d150 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
2d160 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
2d170 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
2d180 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
2d190 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
2d1a0 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
2d1b0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
2d1c0 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
2d1d0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
2d1e0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
2d1f0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
2d200 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
2d210 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
2d220 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
2d230 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
2d240 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
2d250 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
2d260 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
2d270 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
2d280 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
2d290 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
2d2a0 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
2d2b0 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
2d2c0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
2d2d0 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
2d2e0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
2d2f0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
2d300 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
2d310 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
2d320 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
2d330 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
2d340 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
2d350 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
2d360 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
2d370 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
2d380 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
2d390 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
2d3a0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
2d3b0 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
2d3c0 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
2d3d0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
2d3e0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
2d3f0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
2d400 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2d410 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
2d420 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d430 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2d440 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2d450 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2d460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d470 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2d480 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
2d490 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
2d4a0 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
2d4b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d4c0 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
2d4d0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
2d4e0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
2d4f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2d500 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
2d510 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
2d520 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
2d530 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2d540 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d550 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2d560 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2d570 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2d580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2d590 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2d5a0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2d5b0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2d5c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d5d0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
2d5e0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
2d5f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
2d600 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
2d610 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
2d620 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
2d630 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d640 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
2d650 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
2d660 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
2d670 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
2d680 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2d690 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
2d6a0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2d6b0 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2d6c0 73 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  s..*/.void *sqli
2d6d0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2d6e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2d6f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
2d700 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
2d710 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
2d720 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
2d730 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
2d740 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
2d750 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
2d760 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
2d770 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
2d780 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
2d790 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2d7a0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
2d7b0 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
2d7c0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2d7d0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
2d7e0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
2d7f0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
2d800 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d810 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
2d820 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
2d830 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
2d840 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
2d850 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
2d860 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
2d870 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2d880 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
2d890 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
2d8a0 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
2d8b0 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
2d8c0 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
2d8d0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
2d8e0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
2d8f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
2d900 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
2d910 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
2d920 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
2d930 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
2d940 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
2d950 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
2d960 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
2d970 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
2d980 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
2d990 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
2d9a0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
2d9b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2d9c0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2d9d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
2d9e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
2d9f0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
2da00 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
2da10 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
2da20 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
2da30 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
2da40 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
2da50 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
2da60 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
2da70 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
2da80 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2da90 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
2daa0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
2dab0 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
2dac0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
2dad0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2dae0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
2daf0 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
2db00 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
2db10 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
2db20 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
2db30 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
2db40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2db50 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
2db60 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
2db70 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
2db80 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
2db90 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
2dba0 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
2dbb0 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
2dbc0 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
2dbd0 20 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71   Mode].*/.int sq
2dbe0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
2dbf0 72 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a  red_cache(int);.
2dc00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2dc10 20 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65   Attempt To Free
2dc20 20 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a   Heap Memory.**.
2dc30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dc40 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2dc50 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2dc60 70 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79  pts to free N by
2dc70 74 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d  tes.** of heap m
2dc80 65 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63  emory by dealloc
2dc90 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74  ating non-essent
2dca0 69 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ial memory alloc
2dcb0 61 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62  ations.** held b
2dcc0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c  y the database l
2dcd0 69 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79  ibrary.   Memory
2dce0 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
2dcf0 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
2dd00 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
2dd10 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
2dd20 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
2dd30 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
2dd40 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  * ^sqlite3_relea
2dd50 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75  se_memory() retu
2dd60 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2dd70 66 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79  f bytes actually
2dd80 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68   freed,.** which
2dd90 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
2dda0 72 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  r less than the 
2ddb0 61 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64  amount requested
2ddc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ddd0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2dde0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2ddf0 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20  I3REF: Impose A 
2de00 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69  Limit On Heap Si
2de10 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ze.**.** ^The sq
2de20 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
2de30 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
2de40 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  e places a "soft
2de50 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68  " limit.** on th
2de60 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
2de70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
2de80 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
2de90 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20   SQLite..** ^If 
2dea0 61 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f  an internal allo
2deb0 63 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  cation is reques
2dec0 74 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65  ted that would e
2ded0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66  xceed the.** sof
2dee0 74 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73  t heap limit, [s
2def0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2df00 65 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f  emory()] is invo
2df10 6b 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f  ked one or.** mo
2df20 72 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65  re times to free
2df30 20 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62   up some space b
2df40 65 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61  efore the alloca
2df50 74 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  tion is performe
2df60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69  d..**.** ^The li
2df70 6d 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73  mit is called "s
2df80 6f 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20  oft" because if 
2df90 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2dfa0 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61  _memory()].** ca
2dfb0 6e 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63  nnot free suffic
2dfc0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70  ient memory to p
2dfd0 72 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74  revent the limit
2dfe0 20 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65   from being exce
2dff0 65 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d  eded,.** the mem
2e000 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
2e010 20 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20   anyway and the 
2e020 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
2e030 6e 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a  n proceeds..**.*
2e040 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72  * ^A negative or
2e050 20 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20   zero value for 
2e060 4e 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  N means that the
2e070 72 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65  re is no soft he
2e080 61 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20  ap limit and.** 
2e090 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  [sqlite3_release
2e0a0 5f 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20  _memory()] will 
2e0b0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
2e0c0 68 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78  hen memory is ex
2e0d0 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  hausted..** ^The
2e0e0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
2e0f0 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  or the soft heap
2e100 20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a   limit is zero..
2e110 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d  **.** ^(SQLite m
2e120 61 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f  akes a best effo
2e130 72 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20  rt to honor the 
2e140 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
2e150 0a 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73  .** But if the s
2e160 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
2e170 61 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64  annot be honored
2e180 2c 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c  , execution will
2e190 0a 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74  .** continue wit
2e1a0 68 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f  hout error or no
2e1b0 74 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54  tification.)^  T
2e1c0 68 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c  his is why the l
2e1d0 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  imit is.** calle
2e1e0 64 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74  d a "soft" limit
2e1f0 2e 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72  .  It is advisor
2e200 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72  y only..**.** Pr
2e210 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
2e220 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69  rsion 3.5.0, thi
2e230 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63  s routine only c
2e240 6f 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d  onstrained the m
2e250 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2e260 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ed by a single t
2e270 68 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65  hread - the same
2e280 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2e290 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
2e2a0 20 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e   runs.  Beginnin
2e2b0 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
2e2c0 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65  rsion 3.5.0, the
2e2d0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2e2e0 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74   is.** applied t
2e2f0 6f 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54  o all threads. T
2e300 68 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  he value specifi
2e310 65 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20  ed for the soft 
2e320 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73  heap limit.** is
2e330 20 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20   an upper bound 
2e340 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d  on the total mem
2e350 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2e360 6f 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20  or all threads. 
2e370 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e  In.** version 3.
2e380 35 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20  5.0 there is no 
2e390 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69  mechanism for li
2e3a0 6d 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20  miting the heap 
2e3b0 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64  usage for.** ind
2e3c0 69 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e  ividual threads.
2e3d0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2e3e0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2e3f0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2e400 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
2e410 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
2e420 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
2e430 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  le.**.** ^This r
2e440 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2e450 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2e460 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2e470 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2e480 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2e490 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2e4a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2e4b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2e4c0 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2e4d0 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2e4e0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2e4f0 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
2e500 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2e510 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2e520 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2e530 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2e540 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65  s function. ^The
2e550 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2e560 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  r is either the 
2e570 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2e580 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d  base.** (i.e. "m
2e590 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72  ain", "temp", or
2e5a0 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
2e5b0 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
2e5c0 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
2e5d0 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
2e5e0 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c  . ^If it is NULL
2e5f0 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63  , then all attac
2e600 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72  hed databases ar
2e610 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f  e searched.** fo
2e620 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e  r the table usin
2e630 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
2e640 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65  ithm used by the
2e650 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2e660 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75   to.** resolve u
2e670 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65  nqualified table
2e680 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a   references..**.
2e690 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e  ** ^The third an
2e6a0 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  d fourth paramet
2e6b0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2e6c0 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62  tion are the tab
2e6d0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a  le and column.**
2e6e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73   name of the des
2e6f0 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73  ired column, res
2e700 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68  pectively. Neith
2e710 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61  er of these para
2e720 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65  meters.** may be
2e730 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65   NULL..**.** ^Me
2e740 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e  tadata is return
2e750 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f  ed by writing to
2e760 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61   the memory loca
2e770 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20  tions passed as 
2e780 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73  the 5th.** and s
2e790 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65  ubsequent parame
2e7a0 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2e7b0 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74  ction. ^Any of t
2e7c0 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
2e7d0 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
2e7e0 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2e7f0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
2e800 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61  lement of metada
2e810 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  ta is omitted..*
2e820 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f  *.** ^(<blockquo
2e830 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2e840 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2e850 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20  ><th> Parameter 
2e860 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54  <th> Output<br>T
2e870 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69  ype <th>  Descri
2e880 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  ption.**.** <tr>
2e890 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f  <td> 5th <td> co
2e8a0 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44  nst char* <td> D
2e8b0 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e  ata type.** <tr>
2e8c0 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f  <td> 6th <td> co
2e8d0 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e  nst char* <td> N
2e8e0 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63  ame of default c
2e8f0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2e900 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74  e.** <tr><td> 7t
2e910 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2e920 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2e930 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54  column has a NOT
2e940 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74   NULL constraint
2e950 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68  .** <tr><td> 8th
2e960 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2e970 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2e980 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66  olumn is part of
2e990 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59   the PRIMARY KEY
2e9a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68  .** <tr><td> 9th
2e9b0 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2e9c0 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2e9d0 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e  olumn is [AUTOIN
2e9e0 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61  CREMENT].** </ta
2e9f0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
2ea00 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
2ea10 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
2ea20 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72  d to by the char
2ea30 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72  acter pointers r
2ea40 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a  eturned for the.
2ea50 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74  ** declaration t
2ea60 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f  ype and collatio
2ea70 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61  n sequence is va
2ea80 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74  lid only until t
2ea90 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20  he next.** call 
2eaa0 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50  to any SQLite AP
2eab0 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  I function..**.*
2eac0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2ead0 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74  ied table is act
2eae0 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e  ually a view, an
2eaf0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2eb00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2eb10 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2eb20 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f  ed column is "ro
2eb30 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22  wid", "oid" or "
2eb40 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a  _rowid_" and an.
2eb50 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  ** [INTEGER PRIM
2eb60 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20  ARY KEY] column 
2eb70 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69  has been explici
2eb80 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68  tly declared, th
2eb90 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2eba0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2ebb0 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c  set for the expl
2ebc0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2ebd0 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65  column. ^(If the
2ebe0 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c  re is no.** expl
2ebf0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
2ec00 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
2ec10 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68   KEY] column, th
2ec20 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a  en the output.**
2ec30 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2ec40 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  set as follows:.
2ec50 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20  **.** <pre>.**  
2ec60 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49     data type: "I
2ec70 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63  NTEGER".**     c
2ec80 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2ec90 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20  e: "BINARY".**  
2eca0 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a     not null: 0.*
2ecb0 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65  *     primary ke
2ecc0 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f  y: 1.**     auto
2ecd0 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a   increment: 0.**
2ece0 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20   </pre>)^.**.** 
2ecf0 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
2ed00 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20  may load one or 
2ed10 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f  more schemas fro
2ed20 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  m database files
2ed30 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  . If an.** error
2ed40 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2ed50 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  his process, or 
2ed60 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64  if the requested
2ed70 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
2ed80 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f  .** cannot be fo
2ed90 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  und, an [error c
2eda0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2edb0 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65   and an error me
2edc0 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e  ssage left.** in
2edd0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ede0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62  onnection] (to b
2edf0 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e  e retrieved usin
2ee00 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  g sqlite3_errmsg
2ee10 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()).)^.**.** ^Th
2ee20 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
2ee30 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2ee40 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2ee50 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2ee60 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2ee70 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2ee80 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2ee90 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
2eea0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
2eeb0 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
2eec0 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
2eed0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2eee0 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
2eef0 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
2ef00 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
2ef10 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
2ef20 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
2ef30 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
2ef40 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
2ef50 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
2ef60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2ef70 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
2ef80 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
2ef90 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2efa0 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
2efb0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
2efc0 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
2efd0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
2efe0 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
2eff0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
2f000 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2f010 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
2f020 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
2f030 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2f040 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
2f050 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
2f060 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
2f070 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
2f080 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2f090 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
2f0a0 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
2f0b0 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
2f0c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2f0d0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
2f0e0 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
2f0f0 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
2f100 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
2f110 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a  ad An Extension.
2f120 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
2f130 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53  rface loads an S
2f140 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20  QLite extension 
2f150 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65  library from the
2f160 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a   named file..**.
2f170 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f180 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2f190 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2f1a0 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a  pts to load an.*
2f1b0 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69  * SQLite extensi
2f1c0 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  on library conta
2f1d0 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65  ined in the file
2f1e0 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   zFile..**.** ^T
2f1f0 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69  he entry point i
2f200 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72  s zProc..** ^zPr
2f210 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20  oc may be 0, in 
2f220 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
2f230 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79  ame of the entry
2f240 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c   point.** defaul
2f250 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65  ts to "sqlite3_e
2f260 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a  xtension_init"..
2f270 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f280 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2f290 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f2a0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  ns.** [SQLITE_OK
2f2b0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
2f2c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2f2d0 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65  if something goe
2f2e0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20  s wrong..** ^If 
2f2f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
2f300 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20  and pzErrMsg is 
2f310 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a  not 0, then the.
2f320 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  ** [sqlite3_load
2f330 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e  _extension()] in
2f340 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74  terface shall at
2f350 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c  tempt to.** fill
2f360 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20   *pzErrMsg with 
2f370 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
2f380 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d  xt stored in mem
2f390 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20  ory.** obtained 
2f3a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2f3b0 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c  lloc()]. The cal
2f3c0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  ling function.**
2f3d0 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69   should free thi
2f3e0 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c  s memory by call
2f3f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2f400 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74  e()]..**.** ^Ext
2f410 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d  ension loading m
2f420 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75  ust be enabled u
2f430 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2f440 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
2f450 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20  ension()] prior 
2f460 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  to calling this 
2f470 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73  API,.** otherwis
2f480 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20  e an error will 
2f490 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  be returned..**.
2f4a0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2f4b0 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
2f4c0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
2f4d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f4e0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
2f4f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2f500 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
2f510 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
2f520 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
2f530 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
2f540 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
2f550 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
2f560 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
2f570 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
2f580 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
2f590 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
2f5a0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
2f5b0 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
2f5c0 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
2f5d0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
2f5e0 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
2f5f0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
2f600 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
2f610 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f620 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
2f630 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
2f640 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
2f650 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
2f660 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
2f670 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
2f680 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
2f690 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
2f6a0 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
2f6b0 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
2f6c0 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
2f6d0 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
2f6e0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
2f6f0 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
2f700 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
2f710 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
2f720 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
2f730 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
2f740 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2f750 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
2f760 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
2f770 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
2f780 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
2f790 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
2f7a0 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
2f7b0 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
2f7c0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
2f7d0 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
2f7e0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
2f7f0 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
2f800 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
2f810 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
2f820 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
2f830 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
2f840 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  again..*/.int sq
2f850 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
2f860 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69  d_extension(sqli
2f870 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f  te3 *db, int ono
2f880 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
2f890 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61  3REF: Automatica
2f8a0 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  lly Load An Exte
2f8b0 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  nsions.**.** ^Th
2f8c0 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e  is API can be in
2f8d0 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d  voked at program
2f8e0 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65   startup in orde
2f8f0 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  r to register.**
2f900 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61   one or more sta
2f910 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65  tically linked e
2f920 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77  xtensions that w
2f930 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65  ill be available
2f940 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b  .** to all new [
2f950 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f960 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ions]..**.** ^(T
2f970 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
2f980 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
2f990 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e  the extension en
2f9a0 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20  try point.** in 
2f9b0 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73  an array that is
2f9c0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2f9d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2f9e0 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a  ].  That memory.
2f9f0 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65  ** is deallocate
2fa00 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65  d by [sqlite3_re
2fa10 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2fa20 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  on()].)^.**.** ^
2fa30 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
2fa40 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e  gisters an exten
2fa50 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74  sion entry point
2fa60 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f   that is.** auto
2fa70 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65  matically invoke
2fa80 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77  d whenever a new
2fa90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2faa0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65  ction].** is ope
2fab0 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ned using [sqlit
2fac0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2fad0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
2fae0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
2faf0 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44  pen_v2()]..** ^D
2fb00 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69  uplicate extensi
2fb10 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ons are detected
2fb20 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   so calling this
2fb30 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74   routine.** mult
2fb40 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20  iple times with 
2fb50 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69  the same extensi
2fb60 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a  on is harmless..
2fb70 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78  ** ^Automatic ex
2fb80 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61  tensions apply a
2fb90 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64  cross all thread
2fba0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2fbb0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
2fbc0 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
2fbd0 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
2fbe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2fbf0 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
2fc00 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
2fc10 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
2fc20 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61  ction disables a
2fc30 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ll previously re
2fc40 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74  gistered automat
2fc50 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73  ic.** extensions
2fc60 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20  . It undoes the 
2fc70 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72  effect of all pr
2fc80 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ior.** [sqlite3_
2fc90 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
2fca0 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a  ] calls.)^.**.**
2fcb0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
2fcc0 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74  disables automat
2fcd0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e  ic extensions in
2fce0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f   all threads..*/
2fcf0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2fd00 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  set_auto_extensi
2fd10 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  on(void);../*.**
2fd20 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  **** EXPERIMENTA
2fd30 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63  L - subject to c
2fd40 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f  hange without no
2fd50 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  tice ***********
2fd60 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ***.**.** The in
2fd70 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76  terface to the v
2fd80 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
2fd90 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e  hanism is curren
2fda0 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a  tly considered.*
2fdb0 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65  * to be experime
2fdc0 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72  ntal.  The inter
2fdd0 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67  face might chang
2fde0 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c  e in incompatibl
2fdf0 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68  e ways..** If th
2fe00 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20  is is a problem 
2fe10 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20  for you, do not 
2fe20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63  use the interfac
2fe30 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a  e at this time..
2fe40 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76  **.** When the v
2fe50 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63  irtual-table mec
2fe60 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65  hanism stabilize
2fe70 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61  s, we will decla
2fe80 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66  re the.** interf
2fe90 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f  ace fixed, suppo
2fea0 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65  rt it indefinite
2feb0 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74  ly, and remove t
2fec0 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a  his comment..*/.
2fed0 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65  ./*.** Structure
2fee0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69  s used by the vi
2fef0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65  rtual table inte
2ff00 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66  rface.*/.typedef
2ff10 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2ff20 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61  vtab sqlite3_vta
2ff30 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  b;.typedef struc
2ff40 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
2ff50 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64  info sqlite3_ind
2ff60 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66  ex_info;.typedef
2ff70 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2ff80 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69  vtab_cursor sqli
2ff90 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b  te3_vtab_cursor;
2ffa0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2ffb0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73  sqlite3_module s
2ffc0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a  qlite3_module;..
2ffd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ffe0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62  Virtual Table Ob
2fff0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
30000 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  : sqlite3_module
30010 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   {virtual table 
30020 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 52  module}.** EXPER
30030 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
30040 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f  is structure, so
30050 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61  metimes called a
30060 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c   a "virtual tabl
30070 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64  e module", .** d
30080 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65  efines the imple
30090 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b  mentation of a [
300a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
300b0 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63    .** This struc
300c0 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f  ture consists mo
300d0 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20  stly of methods 
300e0 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
300f0 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c  **.** ^A virtual
30100 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73   table module is
30110 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c   created by fill
30120 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74  ing in a persist
30130 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20  ent.** instance 
30140 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
30150 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20  e and passing a 
30160 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
30170 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b  instance.** to [
30180 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
30190 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c  odule()] or [sql
301a0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
301b0 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  le_v2()]..** ^Th
301c0 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72  e registration r
301d0 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74  emains valid unt
301e0 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65  il it is replace
301f0 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74  d by a different
30200 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e  .** module or un
30210 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73  til the [databas
30220 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c  e connection] cl
30230 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65  oses.  The conte
30240 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74  nt.** of this st
30250 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74  ructure must not
30260 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74   change while it
30270 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77   is registered w
30280 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62  ith.** any datab
30290 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
302a0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
302b0 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74  3_module {.  int
302c0 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74   iVersion;.  int
302d0 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69   (*xCreate)(sqli
302e0 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78  te3*, void *pAux
302f0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30300 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74   int argc, const
30310 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67   char *const*arg
30320 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  v,.             
30330 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
30340 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29  *ppVTab, char**)
30350 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65  ;.  int (*xConne
30360 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ct)(sqlite3*, vo
30370 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20  id *pAux,.      
30380 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
30390 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63  c, const char *c
303a0 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20  onst*argv,.     
303b0 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65            sqlite
303c0 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c  3_vtab **ppVTab,
303d0 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20   char**);.  int 
303e0 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71  (*xBestIndex)(sq
303f0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30400 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  b, sqlite3_index
30410 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28  _info*);.  int (
30420 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71  *xDisconnect)(sq
30430 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
30440 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73  b);.  int (*xDes
30450 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74  troy)(sqlite3_vt
30460 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
30470 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
30480 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
30490 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
304a0 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b  sor **ppCursor);
304b0 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
304c0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
304d0 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  rsor*);.  int (*
304e0 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33  xFilter)(sqlite3
304f0 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69  _vtab_cursor*, i
30500 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74  nt idxNum, const
30510 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20   char *idxStr,. 
30520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
30530 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33  nt argc, sqlite3
30540 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a  _value **argv);.
30550 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73    int (*xNext)(s
30560 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30570 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45  or*);.  int (*xE
30580 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  of)(sqlite3_vtab
30590 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
305a0 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69   (*xColumn)(sqli
305b0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
305c0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  , sqlite3_contex
305d0 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  t*, int);.  int 
305e0 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65  (*xRowid)(sqlite
305f0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
30600 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
30610 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a  Rowid);.  int (*
30620 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33  xUpdate)(sqlite3
30630 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71  _vtab *, int, sq
30640 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20  lite3_value **, 
30650 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29  sqlite3_int64 *)
30660 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e  ;.  int (*xBegin
30670 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
30680 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
30690 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76  xSync)(sqlite3_v
306a0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
306b0 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71  nt (*xCommit)(sq
306c0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61  lite3_vtab *pVTa
306d0 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c  b);.  int (*xRol
306e0 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76  lback)(sqlite3_v
306f0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
30700 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69  nt (*xFindFuncti
30710 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  on)(sqlite3_vtab
30720 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72   *pVtab, int nAr
30730 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  g, const char *z
30740 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20  Name,.          
30750 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
30760 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c  d (**pxFunc)(sql
30770 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
30780 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
30790 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  *),.            
307a0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
307b0 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  **ppArg);.  int 
307c0 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
307d0 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20  e3_vtab *pVtab, 
307e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77  const char *zNew
307f0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  );.};../*.** CAP
30800 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
30810 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e  able Indexing In
30820 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59  formation.** KEY
30830 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69  WORDS: sqlite3_i
30840 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50  ndex_info.** EXP
30850 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
30860 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  The sqlite3_inde
30870 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
30880 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75   and its substru
30890 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 74  ctures is used t
308a0 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d  o.** pass inform
308b0 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72  ation into and r
308c0 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c 79  eceive the reply
308d0 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73 74   from the [xBest
308e0 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64  Index].** method
308f0 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
30900 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54  able module].  T
30910 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72 20  he fields under 
30920 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20 74  **Inputs** are t
30930 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20  he.** inputs to 
30940 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20 61  xBestIndex and a
30950 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78  re read-only.  x
30960 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72 74  BestIndex insert
30970 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73  s its.** results
30980 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70   into the **Outp
30990 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a  uts** fields..**
309a0 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73 74  .** ^(The aConst
309b0 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72 65  raint[] array re
309c0 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61 75  cords WHERE clau
309d0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 6f  se constraints o
309e0 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a  f the form:.**.*
309f0 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f 50  * <pre>column OP
30a00 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a   expr</pre>.**.*
30a10 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
30a20 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
30a30 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20  t;, or &gt;=.)^ 
30a40 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61   ^(The particula
30a50 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
30a60 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
30a70 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 29 5e 20 20  traint[].op.)^  
30a80 5e 28 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74  ^(The index of t
30a90 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f  he column is sto
30aa0 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74  red in.** aConst
30ab0 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e  raint[].iColumn.
30ac0 29 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e  )^  ^(aConstrain
30ad0 74 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52  t[].usable is TR
30ae0 55 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70  UE if the.** exp
30af0 72 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68  r on the right-h
30b00 61 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20  and side can be 
30b10 65 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74  evaluated (and t
30b20 68 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hus the constrai
30b30 6e 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29  nt.** is usable)
30b40 20 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74   and false if it
30b50 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a   cannot.)^.**.**
30b60 20 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20   ^The optimizer 
30b70 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e  automatically in
30b80 76 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74  verts terms of t
30b90 68 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50  he form "expr OP
30ba0 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20   column".** and 
30bb0 6d 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70  makes other simp
30bc0 6c 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74  lifications to t
30bd0 68 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  he WHERE clause 
30be0 69 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f  in an attempt to
30bf0 0a 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20  .** get as many 
30c00 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
30c10 6d 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d  ms into the form
30c20 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20   shown above as 
30c30 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68  possible..** ^Th
30c40 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  e aConstraint[] 
30c50 61 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72  array only repor
30c60 74 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ts WHERE clause 
30c70 74 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a  terms that are.*
30c80 2a 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68  * relevant to th
30c90 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72  e particular vir
30ca0 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67  tual table being
30cb0 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20   queried..**.** 
30cc0 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f  ^Information abo
30cd0 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  ut the ORDER BY 
30ce0 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64  clause is stored
30cf0 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a   in aOrderBy[]..
30d00 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66  ** ^Each term of
30d10 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
30d20 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
30d30 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
30d40 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42  e..**.** The [xB
30d50 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64  estIndex] method
30d60 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
30d70 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
30d80 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
30d90 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
30da0 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
30db0 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66  to xFilter.  ^If
30dc0 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65   argvIndex>0 the
30dd0 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68  n.** the right-h
30de0 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20  and side of the 
30df0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43  corresponding aC
30e00 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65  onstraint[] is e
30e10 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20  valuated.** and 
30e20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76  becomes the argv
30e30 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69  Index-th entry i
30e40 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43  n argv.  ^(If aC
30e50 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d  onstraintUsage[]
30e60 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65  .omit.** is true
30e70 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74  , then the const
30e80 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64  raint is assumed
30e90 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e   to be fully han
30ea0 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76  dled by the.** v
30eb0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64  irtual table and
30ec0 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20   is not checked 
30ed0 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e  again by SQLite.
30ee0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64  )^.**.** ^The id
30ef0 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20  xNum and idxPtr 
30f00 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72  values are recor
30f10 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69  ded and passed i
30f20 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c  nto the.** [xFil
30f30 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20  ter] method..** 
30f40 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  ^[sqlite3_free()
30f50 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65  ] is used to fre
30f60 65 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20  e idxPtr if and 
30f70 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54  only if.** needT
30f80 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
30f90 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rue..**.** ^The 
30fa0 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20  orderByConsumed 
30fb0 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75  means that outpu
30fc0 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d  t from [xFilter]
30fd0 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63  /[xNext] will oc
30fe0 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f  cur in.** the co
30ff0 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73  rrect order to s
31000 61 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52  atisfy the ORDER
31010 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68   BY clause so th
31020 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a  at no separate.*
31030 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69  * sorting step i
31040 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
31050 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64  * ^The estimated
31060 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e  Cost value is an
31070 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65   estimate of the
31080 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74   cost of doing t
31090 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72  he.** particular
310a0 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c   lookup.  A full
310b0 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65   scan of a table
310c0 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20   with N entries 
310d0 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61  should have.** a
310e0 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62   cost of N.  A b
310f0 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20  inary search of 
31100 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74  a table of N ent
31110 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
31120 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70   a.** cost of ap
31130 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28  proximately log(
31140 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  N)..*/.struct sq
31150 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
31160 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a   {.  /* Inputs *
31170 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61  /.  int nConstra
31180 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f  int;           /
31190 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72  * Number of entr
311a0 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69  ies in aConstrai
311b0 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  nt */.  struct s
311c0 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
311d0 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69  straint {.     i
311e0 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
311f0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
31200 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20  mn on left-hand 
31210 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69  side of constrai
31220 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  nt */.     unsig
31230 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20  ned char op;    
31240 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69       /* Constrai
31250 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20  nt operator */. 
31260 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
31270 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a  r usable;     /*
31280 20 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f   True if this co
31290 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62  nstraint is usab
312a0 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69  le */.     int i
312b0 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20  TermOffset;     
312c0 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74       /* Used int
312d0 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49  ernally - xBestI
312e0 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f  ndex should igno
312f0 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  re */.  } *aCons
31300 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20  traint;         
31310 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57     /* Table of W
31320 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73  HERE clause cons
31330 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74  traints */.  int
31340 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20   nOrderBy;      
31350 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
31360 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68  r of terms in th
31370 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
31380 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  e */.  struct sq
31390 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65  lite3_index_orde
313a0 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69  rby {.     int i
313b0 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20  Column;         
313c0 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e       /* Column n
313d0 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e  umber */.     un
313e0 73 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63  signed char desc
313f0 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20  ;       /* True 
31400 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65  for DESC.  False
31410 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d   for ASC. */.  }
31420 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20   *aOrderBy;     
31430 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65            /* The
31440 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
31450 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73   */.  /* Outputs
31460 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
31470 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
31480 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20  raint_usage {.  
31490 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b    int argvIndex;
314a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66             /* if
314b0 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20   >0, constraint 
314c0 69 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20  is part of argv 
314d0 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20  to xFilter */.  
314e0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
314f0 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f  omit;      /* Do
31500 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74   not code a test
31510 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72   for this constr
31520 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  aint */.  } *aCo
31530 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20  nstraintUsage;. 
31540 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20   int idxNum;    
31550 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
31560 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64  umber used to id
31570 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78  entify the index
31580 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53   */.  char *idxS
31590 74 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  tr;             
315a0 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73   /* String, poss
315b0 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  ibly obtained fr
315c0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
315d0 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54  c */.  int needT
315e0 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20  oFreeIdxStr;    
315f0 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72    /* Free idxStr
31600 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66   using sqlite3_f
31610 72 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f  ree() if true */
31620 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f  .  int orderByCo
31630 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a  nsumed;       /*
31640 20 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20   True if output 
31650 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72  is already order
31660 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65  ed */.  double e
31670 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20  stimatedCost;   
31680 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20     /* Estimated 
31690 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68  cost of using th
316a0 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23  is index */.};.#
316b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
316c0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45  DEX_CONSTRAINT_E
316d0 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  Q    2.#define S
316e0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
316f0 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23  TRAINT_GT    4.#
31700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
31710 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
31720 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53  E    8.#define S
31730 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
31740 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a  TRAINT_LT    16.
31750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
31760 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
31770 47 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65  GE    32.#define
31780 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
31790 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36  NSTRAINT_MATCH 6
317a0 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
317b0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69  F: Register A Vi
317c0 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c  rtual Table Impl
317d0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 45 58  ementation.** EX
317e0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
317f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
31800 20 61 72 65 20 75 73 65 64 20 74 6f 20 72 65 67   are used to reg
31810 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72  ister a new [vir
31820 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
31830 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64  e] name..** ^Mod
31840 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62  ule names must b
31850 65 20 72 65 67 69 73 74 65 72 65 64 20 62 65 66  e registered bef
31860 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20  ore.** creating 
31870 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74  a new [virtual t
31880 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20  able] using the 
31890 6d 6f 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72  module and befor
318a0 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65  e using a.** pre
318b0 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61  existing [virtua
318c0 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65  l table] for the
318d0 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e   module..**.** ^
318e0 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20  The module name 
318f0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e  is registered on
31900 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
31910 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
31920 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  fied.** by the f
31930 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
31940 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
31950 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65  e module is give
31960 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63  n by the .** sec
31970 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
31980 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
31990 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
319a0 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c  r to.** the impl
319b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
319c0 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
319d0 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65   module].   ^The
319e0 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d   fourth.** param
319f0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
31a00 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61  rary client data
31a10 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
31a20 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a   passed through.
31a30 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72  ** into the [xCr
31a40 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e  eate] and [xConn
31a50 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20  ect] methods of 
31a60 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
31a70 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e  e module.** when
31a80 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74   a new virtual t
31a90 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67  able is be being
31aa0 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e   created or rein
31ab0 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  itialized..**.**
31ac0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
31ad0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
31ae0 20 69 6e 74 65 72 66 61 63 65 20 68 61 73 20 61   interface has a
31af0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
31b00 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
31b10 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74  ointer to a dest
31b20 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70  ructor for the p
31b30 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51  ClientData.  ^SQ
31b40 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76  Lite will.** inv
31b50 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
31b60 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20  or function (if 
31b70 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  it is not NULL) 
31b80 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e  when SQLite.** n
31b90 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74  o longer needs t
31ba0 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70  he pClientData p
31bb0 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 73 71  ointer.  ^The sq
31bc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
31bd0 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ule().** interfa
31be0 63 65 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  ce is equivalent
31bf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61   to sqlite3_crea
31c00 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77  te_module_v2() w
31c10 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65  ith a NULL.** de
31c20 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53 51 4c  structor..*/.SQL
31c30 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
31c40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
31c50 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
31c60 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
31c70 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
31c80 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
31c90 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
31ca0 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
31cb0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
31cc0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
31cd0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
31ce0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
31cf0 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
31d00 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
31d10 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
31d20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20  *pClientData    
31d30 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
31d40 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
31d50 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
31d60 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
31d70 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
31d80 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
31d90 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
31da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31db0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74  * SQLite connect
31dc0 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20  ion to register 
31dd0 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20  module with */. 
31de0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
31df0 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  me,         /* N
31e00 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
31e10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c  e */.  const sql
31e20 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20  ite3_module *p, 
31e30 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
31e40 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
31e50 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61   void *pClientDa
31e60 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43  ta,         /* C
31e70 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78  lient data for x
31e80 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20  Create/xConnect 
31e90 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  */.  void(*xDest
31ea0 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20  roy)(void*)     
31eb0 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75  /* Module destru
31ec0 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  ctor function */
31ed0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
31ee0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
31ef0 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65  le Instance Obje
31f00 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
31f10 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 20  sqlite3_vtab.** 
31f20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
31f30 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
31f40 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
31f50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
31f60 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a  ses a subclass.*
31f70 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  * of this object
31f80 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70   to describe a p
31f90 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e  articular instan
31fa0 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69  ce.** of the [vi
31fb0 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45  rtual table].  E
31fc0 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c  ach subclass wil
31fd0 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64  l.** be tailored
31fe0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
31ff0 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f   needs of the mo
32000 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
32010 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70  ion..** The purp
32020 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65  ose of this supe
32030 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66  rclass is to def
32040 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c  ine certain fiel
32050 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63  ds that are.** c
32060 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64  ommon to all mod
32070 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
32080 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74  ons..**.** ^Virt
32090 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f  ual tables metho
320a0 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72  ds can set an er
320b0 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20 61  ror message by a
320c0 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74  ssigning a.** st
320d0 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
320e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
320f0 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73  ntf()] to zErrMs
32100 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73  g.  The method s
32110 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61  hould.** take ca
32120 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f  re that any prio
32130 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65 65  r string is free
32140 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
32150 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
32160 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69  ** prior to assi
32170 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69  gning a new stri
32180 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  ng to zErrMsg.  
32190 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f 72  ^After the error
321a0 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64   message.** is d
321b0 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20 74  elivered up to t
321c0 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63  he client applic
321d0 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e  ation, the strin
321e0 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  g will be automa
321f0 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64  tically.** freed
32200 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65   by sqlite3_free
32210 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d  () and the zErrM
32220 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65  sg field will be
32230 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75   zeroed..*/.stru
32240 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
32250 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  {.  const sqlite
32260 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c  3_module *pModul
32270 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c  e;  /* The modul
32280 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74 75  e for this virtu
32290 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e  al table */.  in
322a0 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20  t nRef;         
322b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
322c0 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20   NO LONGER USED 
322d0 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d  */.  char *zErrM
322e0 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  sg;             
322f0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65       /* Error me
32300 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74  ssage from sqlit
32310 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a  e3_mprintf() */.
32320 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
32330 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
32340 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
32350 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
32360 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
32370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
32380 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72  irtual Table Cur
32390 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  sor Object.** KE
323a0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
323b0 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72  vtab_cursor {vir
323c0 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f  tual table curso
323d0 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  r}.** EXPERIMENT
323e0 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  AL.**.** Every [
323f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
32400 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
32410 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
32420 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  lass of the.** f
32430 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
32440 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63  re to describe c
32450 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e  ursors that poin
32460 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76  t into the.** [v
32470 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e  irtual table] an
32480 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
32490 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
324a0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
324b0 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
324c0 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
324d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ** [sqlite3_modu
324e0 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e  le.xOpen | xOpen
324f0 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
32500 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64  module and are d
32510 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74  estroyed.** by t
32520 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  he [sqlite3_modu
32530 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f  le.xClose | xClo
32540 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72  se] method.  Cur
32550 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a  sors are used.**
32560 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72   by the [xFilter
32570 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f  ], [xNext], [xEo
32580 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61  f], [xColumn], a
32590 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68  nd [xRowid] meth
325a0 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f  ods.** of the mo
325b0 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75  dule.  Each modu
325c0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
325d0 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a  n will define.**
325e0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
325f0 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75  a cursor structu
32600 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f  re to suit its o
32610 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  wn needs..**.** 
32620 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  This superclass 
32630 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20  exists in order 
32640 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73  to define fields
32650 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74   of the cursor t
32660 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f  hat.** are commo
32670 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  n to all impleme
32680 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72  ntations..*/.str
32690 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
326a0 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69  _cursor {.  sqli
326b0 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b  te3_vtab *pVtab;
326c0 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c        /* Virtual
326d0 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63   table of this c
326e0 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69  ursor */.  /* Vi
326f0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
32700 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
32710 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
32720 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
32730 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
32740 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20  PI3REF: Declare 
32750 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20  The Schema Of A 
32760 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a  Virtual Table.**
32770 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
32780 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74  .** ^The [xCreat
32790 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
327a0 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a  ] methods of a.*
327b0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
327c0 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68   module] call th
327d0 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  is interface.** 
327e0 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20 66  to declare the f
327f0 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73  ormat (the names
32800 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f   and datatypes o
32810 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f  f the columns) o
32820 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c  f.** the virtual
32830 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70   tables they imp
32840 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54  lement..*/.SQLIT
32850 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
32860 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61  nt sqlite3_decla
32870 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a  re_vtab(sqlite3*
32880 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
32890 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  QL);../*.** CAPI
328a0 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41  3REF: Overload A
328b0 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20   Function For A 
328c0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a  Virtual Table.**
328d0 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
328e0 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61  .** ^(Virtual ta
328f0 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65  bles can provide
32900 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70   alternative imp
32910 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32920 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69  functions.** usi
32930 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e  ng the [xFindFun
32940 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  ction] method of
32950 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
32960 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a  ble module].  .*
32970 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72  * But global ver
32980 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66  sions of those f
32990 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74  unctions.** must
329a0 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20   exist in order 
329b0 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  to be overloaded
329c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  .)^.**.** ^(This
329d0 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20   API makes sure 
329e0 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e  a global version
329f0 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77   of a function w
32a00 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
32a10 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d  .** name and num
32a20 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72  ber of parameter
32a30 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f  s exists.  If no
32a40 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65   such function e
32a50 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20  xists.** before 
32a60 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c  this API is call
32a70 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69  ed, a new functi
32a80 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e  on is created.)^
32a90 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74    ^The implement
32aa0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
32ab0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77  new function alw
32ac0 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78  ays causes an ex
32ad0 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  ception to be th
32ae0 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65  rown.  So.** the
32af0 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
32b00 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e   not good for an
32b10 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66  ything by itself
32b20 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70  .  Its only.** p
32b30 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20  urpose is to be 
32b40 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75  a placeholder fu
32b50 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
32b60 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
32b70 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74   by a [virtual t
32b80 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  able]..*/.SQLITE
32b90 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
32ba0 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f  t sqlite3_overlo
32bb0 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69  ad_function(sqli
32bc0 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
32bd0 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74   *zFuncName, int
32be0 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54   nArg);../*.** T
32bf0 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
32c00 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
32c10 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69  e mechanism defi
32c20 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20  ned above (back 
32c30 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65  up.** to a comme
32c40 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69  nt remarkably si
32c50 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e  milar to this on
32c60 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  e) is currently 
32c70 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
32c80 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
32c90 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
32ca0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
32cb0 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
32cc0 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
32cd0 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
32ce0 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
32cf0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
32d00 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
32d10 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
32d20 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
32d30 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
32d40 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
32d50 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
32d60 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
32d70 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
32d80 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
32d90 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a  comment..**.****
32da0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
32db0 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
32dc0 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
32dd0 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
32de0 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.*/../*.** CAPI
32df0 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54  3REF: A Handle T
32e00 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a  o An Open BLOB.*
32e10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f  * KEYWORDS: {BLO
32e20 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20  B handle} {BLOB 
32e30 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41  handles}.**.** A
32e40 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
32e50 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
32e60 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f  ents an open BLO
32e70 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73  B on which.** [s
32e80 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
32e90 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
32ea0 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20  LOB I/O] can be 
32eb0 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f  performed..** ^O
32ec0 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20 74  bjects of this t
32ed0 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64 20  ype are created 
32ee0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
32ef0 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  _open()].** and 
32f00 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
32f10 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
32f20 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ()]..** ^The [sq
32f30 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
32f40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32f50 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e  blob_write()] in
32f60 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20  terfaces.** can 
32f70 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  be used to read 
32f80 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73  or write small s
32f90 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68  ubsections of th
32fa0 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20  e BLOB..** ^The 
32fb0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
32fc0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
32fd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
32fe0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e  e of the BLOB in
32ff0 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64   bytes..*/.typed
33000 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
33010 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62  3_blob sqlite3_b
33020 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lob;../*.** CAPI
33030 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f  3REF: Open A BLO
33040 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61  B For Incrementa
33050 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  l I/O.**.** ^(Th
33060 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70  is interfaces op
33070 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64  ens a [BLOB hand
33080 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20  le | handle] to 
33090 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64  the BLOB located
330a0 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c  .** in row iRow,
330b0 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c   column zColumn,
330c0 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e   table zTable in
330d0 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a   database zDb;.*
330e0 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * in other words
330f0 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20  , the same BLOB 
33100 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65  that would be se
33110 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a  lected by:.**.**
33120 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45   <pre>.**     SE
33130 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f  LECT zColumn FRO
33140 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45  M zDb.zTable WHE
33150 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f  RE [rowid] = iRo
33160 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a  w;.** </pre>)^.*
33170 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c 61  *.** ^If the fla
33180 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  gs parameter is 
33190 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
331a0 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65  he BLOB is opene
331b0 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e  d for read.** an
331c0 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e 20  d write access. 
331d0 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c 20  ^If it is zero, 
331e0 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e  the BLOB is open
331f0 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63 65  ed for read acce
33200 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f  ss..** ^It is no
33210 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70  t possible to op
33220 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74  en a column that
33230 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20 69   is part of an i
33240 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79 20  ndex or primary 
33250 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69 74  .** key for writ
33260 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67  ing. ^If [foreig
33270 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
33280 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c 20  s] are enabled, 
33290 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f  it is .** not po
332a0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
332b0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
332c0 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c 64  part of a [child
332d0 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69 6e   key] for writin
332e0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  g..**.** ^Note t
332f0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
33300 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68 65   name is not the
33310 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20 63   filename that c
33320 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64  ontains.** the d
33330 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74 68  atabase but rath
33340 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63 20  er the symbolic 
33350 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
33360 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70 70  base that.** app
33370 65 61 72 73 20 61 66 74 65 72 20 74 68 65 20 41  ears after the A
33380 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20 74  S keyword when t
33390 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63  he database is c
333a0 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b  onnected using [
333b0 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72  ATTACH]..** ^For
333c0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
333d0 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74  se file, the dat
333e0 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d  abase name is "m
333f0 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45  ain"..** ^For TE
33400 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64  MP tables, the d
33410 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20  atabase name is 
33420 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28  "temp"..**.** ^(
33430 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c  On success, [SQL
33440 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
33450 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77 20  ned and the new 
33460 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73  [BLOB handle] is
33470 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a   written.** to *
33480 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73  ppBlob. Otherwis
33490 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
334a0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
334b0 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65 74  d *ppBlob is set
334c0 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c  .** to be a null
334d0 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e   pointer.)^.** ^
334e0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 65  This function se
334f0 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ts the [database
33500 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72   connection] err
33510 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
33520 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c  age.** accessibl
33530 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65  e via [sqlite3_e
33540 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73  rrcode()] and [s
33550 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
33560 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20   and related.** 
33570 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65  functions. ^Note
33580 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c 6f   that the *ppBlo
33590 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 6c  b variable is al
335a0 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65 64  ways initialized
335b0 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68 61   in a.** way tha
335c0 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65 20  t makes it safe 
335d0 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  to invoke [sqlit
335e0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
335f0 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72   on *ppBlob.** r
33600 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
33610 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
33620 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ure of this rout
33630 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ine..**.** ^(If 
33640 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42  the row that a B
33650 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74  LOB handle point
33660 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64  s to is modified
33670 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54   by an.** [UPDAT
33680 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72  E], [DELETE], or
33690 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54   by [ON CONFLICT
336a0 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a  ] side-effects.*
336b0 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  * then the BLOB 
336c0 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64  handle is marked
336d0 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a   as "expired"..*
336e0 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69  * This is true i
336f0 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20  f any column of 
33700 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67  the row is chang
33710 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d  ed, even a colum
33720 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  n.** other than 
33730 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42  the one the BLOB
33740 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20   handle is open 
33750 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20  on.)^.** ^Calls 
33760 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
33770 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
33780 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
33790 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70  ()] for.** a exp
337a0 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65  ired BLOB handle
337b0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72 65   fail with an re
337c0 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51  turn code of [SQ
337d0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20  LITE_ABORT]..** 
337e0 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74 74 65  ^(Changes writte
337f0 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72  n into a BLOB pr
33800 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  ior to the BLOB 
33810 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f 74  expiring are not
33820 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
33830 62 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f  by the expiratio
33840 6e 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20  n of the BLOB.  
33850 53 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c  Such changes wil
33860 6c 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20  l eventually.** 
33870 63 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72  commit if the tr
33880 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e  ansaction contin
33890 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
338a0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20  n.)^.**.** ^Use 
338b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
338c0 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
338d0 66 61 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e  face to determin
338e0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  e the size of.**
338f0 20 74 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62   the opened blob
33900 2e 20 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20  .  ^The size of 
33910 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62  a blob may not b
33920 65 20 63 68 61 6e 67 65 64 20 62 79 20 74 68 69  e changed by thi
33930 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20  s.** interface. 
33940 20 55 73 65 20 74 68 65 20 5b 55 50 44 41 54 45   Use the [UPDATE
33950 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f  ] SQL command to
33960 20 63 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65   change the size
33970 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a   of a.** blob..*
33980 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
33990 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
339a0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
339b0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
339c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
339d0 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d  * and the built-
339e0 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51  in [zeroblob] SQ
339f0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62  L function can b
33a00 65 20 75 73 65 64 2c 20 69 66 20 64 65 73 69 72  e used, if desir
33a10 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65  ed,.** to create
33a20 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d   an empty, zero-
33a30 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77  filled blob in w
33a40 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20  hich to read or 
33a50 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74  write using.** t
33a60 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
33a70 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20  *.** To avoid a 
33a80 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65  resource leak, e
33a90 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  very open [BLOB 
33aa0 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65  handle] should e
33ab0 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20  ventually.** be 
33ac0 72 65 6c 65 61 73 65 64 20 62 79 20 61 20 63 61  released by a ca
33ad0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
33ae0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f  lob_close()]..*/
33af0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
33b00 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65  b_open(.  sqlite
33b10 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  3*,.  const char
33b20 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63   *zDb,.  const c
33b30 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63  har *zTable,.  c
33b40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
33b50 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e  mn,.  sqlite3_in
33b60 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20  t64 iRow,.  int 
33b70 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33  flags,.  sqlite3
33b80 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29  _blob **ppBlob.)
33b90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33ba0 46 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20  F: Close A BLOB 
33bb0 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c  Handle.**.** ^Cl
33bc0 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  oses an open [BL
33bd0 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a  OB handle]..**.*
33be0 2a 20 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f  * ^Closing a BLO
33bf0 42 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68  B shall cause th
33c00 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  e current transa
33c10 63 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a  ction to commit.
33c20 2a 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20  ** if there are 
33c30 6e 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20  no other BLOBs, 
33c40 6e 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61  no pending prepa
33c50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20  red statements, 
33c60 61 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  and the.** datab
33c70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
33c80 73 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74  s in [autocommit
33c90 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61   mode]..** ^If a
33ca0 6e 79 20 77 72 69 74 65 73 20 77 65 72 65 20 6d  ny writes were m
33cb0 61 64 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c  ade to the BLOB,
33cc0 20 74 68 65 79 20 6d 69 67 68 74 20 62 65 20 68   they might be h
33cd0 65 6c 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20  eld in cache.** 
33ce0 75 6e 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20  until the close 
33cf0 6f 70 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65  operation if the
33d00 79 20 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a  y will fit..**.*
33d10 2a 20 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20  * ^(Closing the 
33d20 42 4c 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65  BLOB often force
33d30 73 20 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a  s the changes.**
33d40 20 6f 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64   out to disk and
33d50 20 73 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65   so if any I/O e
33d60 72 72 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65  rrors occur, the
33d70 79 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63  y will likely oc
33d80 63 75 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69  cur.** at the ti
33d90 6d 65 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42  me when the BLOB
33da0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79   is closed.  Any
33db0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
33dc0 75 72 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f  ur during.** clo
33dd0 73 69 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65  sing are reporte
33de0 64 20 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  d as a non-zero 
33df0 72 65 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a  return value.)^.
33e00 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42  **.** ^(The BLOB
33e10 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e   is closed uncon
33e20 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65  ditionally.  Eve
33e30 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e  n if this routin
33e40 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20  e returns.** an 
33e50 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20  error code, the 
33e60 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c  BLOB is still cl
33e70 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43  osed.)^.**.** ^C
33e80 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
33e90 69 6e 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20  ine with a null 
33ea0 70 6f 69 6e 74 65 72 20 28 73 75 63 68 20 61 73  pointer (such as
33eb0 20 77 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e   would be return
33ec0 65 64 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65  ed.** by a faile
33ed0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
33ee0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29  e3_blob_open()])
33ef0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
33f00 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  o-op..*/.int sql
33f10 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
33f20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b  sqlite3_blob *);
33f30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33f40 3a 20 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a  : Return The Siz
33f50 65 20 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f  e Of An Open BLO
33f60 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73  B.**.** ^Returns
33f70 20 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74   the size in byt
33f80 65 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61  es of the BLOB a
33f90 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68  ccessible via th
33fa0 65 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  e .** successful
33fb0 6c 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20  ly opened [BLOB 
33fc0 68 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f  handle] in its o
33fd0 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  nly argument.  ^
33fe0 54 68 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74  The.** increment
33ff0 61 6c 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74  al blob I/O rout
34000 69 6e 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65  ines can only re
34010 61 64 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e  ad or overwritin
34020 67 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c  g existing.** bl
34030 6f 62 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79  ob content; they
34040 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
34050 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
34060 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  b..**.** This ro
34070 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73  utine only works
34080 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64   on a [BLOB hand
34090 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65  le] which has be
340a0 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79  en created.** by
340b0 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
340c0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
340d0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
340e0 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20  ] and which has 
340f0 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73  not.** been clos
34100 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
34110 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50  lob_close()].  P
34120 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  assing any other
34130 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74   pointer in.** t
34140 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  o this routine r
34150 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
34160 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
34170 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
34180 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  avior..*/.int sq
34190 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
341a0 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29  (sqlite3_blob *)
341b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
341c0 46 3a 20 52 65 61 64 20 44 61 74 61 20 46 72 6f  F: Read Data Fro
341d0 6d 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  m A BLOB Increme
341e0 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54  ntally.**.** ^(T
341f0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
34200 75 73 65 64 20 74 6f 20 72 65 61 64 20 64 61 74  used to read dat
34210 61 20 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b  a from an open [
34220 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74  BLOB handle] int
34230 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  o a.** caller-su
34240 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e  pplied buffer. N
34250 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
34260 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62  re copied into b
34270 75 66 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20  uffer Z.** from 
34280 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73  the open BLOB, s
34290 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65  tarting at offse
342a0 74 20 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a  t iOffset.)^.**.
342b0 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f  ** ^If offset iO
342c0 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
342d0 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
342e0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
342f0 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
34300 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
34310 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
34320 73 20 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f  s read.  ^If N o
34330 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20  r iOffset is.** 
34340 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
34350 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
34360 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e  s returned and n
34370 6f 20 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a  o data is read..
34380 2a 2a 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20  ** ^The size of 
34390 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65  the blob (and he
343a0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  nce the maximum 
343b0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73  value of N+iOffs
343c0 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  et).** can be de
343d0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74  termined using t
343e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
343f0 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
34400 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ace..**.** ^An a
34410 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66  ttempt to read f
34420 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b  rom an expired [
34430 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69  BLOB handle] fai
34440 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72  ls with an.** er
34450 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
34460 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
34470 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
34480 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
34490 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
344a0 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77  TE_OK..** Otherw
344b0 69 73 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  ise, an [error c
344c0 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65  ode] or an [exte
344d0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
344e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
344f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
34500 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e  ne only works on
34510 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d   a [BLOB handle]
34520 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20   which has been 
34530 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20  created.** by a 
34540 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
34550 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
34560 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
34570 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74  nd which has not
34580 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20  .** been closed 
34590 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
345a0 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73  _close()].  Pass
345b0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f  ing any other po
345c0 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74  inter in.** to t
345d0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75  his routine resu
345e0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
345f0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
34600 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
34610 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  or..**.** See al
34620 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  so: [sqlite3_blo
34630 62 5f 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69  b_write()]..*/.i
34640 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
34650 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f  read(sqlite3_blo
34660 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e  b *, void *Z, in
34670 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t N, int iOffset
34680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34690 45 46 3a 20 57 72 69 74 65 20 44 61 74 61 20 49  EF: Write Data I
346a0 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65  nto A BLOB Incre
346b0 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e  mentally.**.** ^
346c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
346d0 20 75 73 65 64 20 74 6f 20 77 72 69 74 65 20 64   used to write d
346e0 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e  ata into an open
346f0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66   [BLOB handle] f
34700 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d  rom a.** caller-
34710 73 75 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e  supplied buffer.
34720 20 5e 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74   ^N bytes of dat
34730 61 20 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f  a are copied fro
34740 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a  m the buffer Z.*
34750 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20  * into the open 
34760 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61  BLOB, starting a
34770 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  t offset iOffset
34780 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
34790 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61  [BLOB handle] pa
347a0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
347b0 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e  t argument was n
347c0 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a  ot opened for.**
347d0 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c   writing (the fl
347e0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
347f0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
34800 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29  pen()] was zero)
34810 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69  ,.** this functi
34820 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  on returns [SQLI
34830 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a  TE_READONLY]..**
34840 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
34850 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
34860 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
34870 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20  of the BLOB; it 
34880 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
34890 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
348a0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f  he size of a BLO
348b0 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  B using this API
348c0 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20  ..** ^If offset 
348d0 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20  iOffset is less 
348e0 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f  than N bytes fro
348f0 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  m the end of the
34900 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54   BLOB,.** [SQLIT
34910 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
34920 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
34930 20 69 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49   is written.  ^I
34940 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  f N is.** less t
34950 68 61 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45  han zero [SQLITE
34960 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
34970 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
34980 69 73 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54  is written..** T
34990 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
349a0 4c 4f 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74  LOB (and hence t
349b0 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65  he maximum value
349c0 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a   of N+iOffset).*
349d0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
349e0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73  ned using the [s
349f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
34a00 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  s()] interface..
34a10 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70  **.** ^An attemp
34a20 74 20 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e  t to write to an
34a30 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68   expired [BLOB h
34a40 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74  andle] fails wit
34a50 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f  h an.** error co
34a60 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
34a70 4f 52 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74  ORT].  ^Writes t
34a80 6f 20 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20  o the BLOB that 
34a90 6f 63 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f  occurred.** befo
34aa0 72 65 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e  re the [BLOB han
34ab0 64 6c 65 5d 20 65 78 70 69 72 65 64 20 61 72 65  dle] expired are
34ac0 20 6e 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b   not rolled back
34ad0 20 62 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72   by the.** expir
34ae0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e  ation of the han
34af0 64 6c 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  dle, though of c
34b00 6f 75 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e  ourse those chan
34b10 67 65 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76  ges might.** hav
34b20 65 20 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74  e been overwritt
34b30 65 6e 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  en by the statem
34b40 65 6e 74 20 74 68 61 74 20 65 78 70 69 72 65 64  ent that expired
34b50 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
34b60 0a 2a 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20  .** or by other 
34b70 69 6e 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74  independent stat
34b80 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ements..**.** ^(
34b90 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69  On success, sqli
34ba0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
34bb0 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
34bc0 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  OK..** Otherwise
34bd0 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64  , an  [error cod
34be0 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
34bf0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
34c00 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
34c10 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34c20 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
34c30 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
34c40 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
34c50 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
34c60 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
34c70 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34c80 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
34c90 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
34ca0 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
34cb0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
34cc0 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
34cd0 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
34ce0 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
34cf0 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
34d00 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
34d10 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
34d20 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
34d30 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
34d40 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
34d50 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  read()]..*/.int 
34d60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
34d70 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  te(sqlite3_blob 
34d80 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  *, const void *z
34d90 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66  , int n, int iOf
34da0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
34db0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
34dc0 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65  File System Obje
34dd0 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74  cts.**.** A virt
34de0 75 61 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28  ual filesystem (
34df0 56 46 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69  VFS) is an [sqli
34e00 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a  te3_vfs] object.
34e10 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 75  ** that SQLite u
34e20 73 65 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a  ses to interact.
34e30 2a 2a 20 77 69 74 68 20 74 68 65 20 75 6e 64 65  ** with the unde
34e40 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
34e50 20 73 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53   system.  Most S
34e60 51 4c 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d  QLite builds com
34e70 65 20 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67  e with a.** sing
34e80 6c 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 74  le default VFS t
34e90 68 61 74 20 69 73 20 61 70 70 72 6f 70 72 69 61  hat is appropria
34ea0 74 65 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20  te for the host 
34eb0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77  computer..** New
34ec0 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 72 65   VFSes can be re
34ed0 67 69 73 74 65 72 65 64 20 61 6e 64 20 65 78 69  gistered and exi
34ee0 73 74 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20  sting VFSes can 
34ef0 62 65 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e  be unregistered.
34f00 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
34f10 67 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  g interfaces are
34f20 20 70 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a   provided..**.**
34f30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66   ^The sqlite3_vf
34f40 73 5f 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61  s_find() interfa
34f50 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
34f60 6e 74 65 72 20 74 6f 20 61 20 56 46 53 20 67 69  nter to a VFS gi
34f70 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a  ven its name..**
34f80 20 5e 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65   ^Names are case
34f90 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e   sensitive..** ^
34fa0 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74  Names are zero-t
34fb0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
34fc0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20  strings..** ^If 
34fd0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63  there is no matc
34fe0 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  h, a NULL pointe
34ff0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
35000 2a 20 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69  * ^If zVfsName i
35010 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  s NULL then the 
35020 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72  default VFS is r
35030 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
35040 4e 65 77 20 56 46 53 65 73 20 61 72 65 20 72 65  New VFSes are re
35050 67 69 73 74 65 72 65 64 20 77 69 74 68 20 73 71  gistered with sq
35060 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
35070 65 72 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e  er()..** ^Each n
35080 65 77 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74  ew VFS becomes t
35090 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
350a0 66 20 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66  f the makeDflt f
350b0 6c 61 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e  lag is set..** ^
350c0 54 68 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e  The same VFS can
350d0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
350e0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69  ultiple times wi
350f0 74 68 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a  thout injury..**
35100 20 5e 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69   ^To make an exi
35110 73 74 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74  sting VFS into t
35120 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20  he default VFS, 
35130 72 65 67 69 73 74 65 72 20 69 74 20 61 67 61 69  register it agai
35140 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61  n.** with the ma
35150 6b 65 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e  keDflt flag set.
35160 20 20 49 66 20 74 77 6f 20 64 69 66 66 65 72 65    If two differe
35170 6e 74 20 56 46 53 65 73 20 77 69 74 68 20 74 68  nt VFSes with th
35180 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61  e.** same name a
35190 72 65 20 72 65 67 69 73 74 65 72 65 64 2c 20 74  re registered, t
351a0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
351b0 6e 64 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a  ndefined.  If a.
351c0 2a 2a 20 56 46 53 20 69 73 20 72 65 67 69 73 74  ** VFS is regist
351d0 65 72 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65  ered with a name
351e0 20 74 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72   that is NULL or
351f0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
35200 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ,.** then the be
35210 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
35220 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65  ned..**.** ^Unre
35230 67 69 73 74 65 72 20 61 20 56 46 53 20 77 69 74  gister a VFS wit
35240 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  h the sqlite3_vf
35250 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 20 69  s_unregister() i
35260 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49  nterface..** ^(I
35270 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
35280 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65  S is unregistere
35290 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69  d, another VFS i
352a0 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74  s chosen as.** t
352b0 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65  he default.  The
352c0 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20   choice for the 
352d0 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74  new VFS is arbit
352e0 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74  rary.)^.*/.sqlit
352f0 65 33 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f  e3_vfs *sqlite3_
35300 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63  vfs_find(const c
35310 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a  har *zVfsName);.
35320 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  int sqlite3_vfs_
35330 72 65 67 69 73 74 65 72 28 73 71 6c 69 74 65 33  register(sqlite3
35340 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44  _vfs*, int makeD
35350 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  flt);.int sqlite
35360 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
35370 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a  (sqlite3_vfs*);.
35380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35390 20 4d 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54   Mutexes.**.** T
353a0 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
353b0 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
353c0 65 73 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a  es for thread.**
353d0 20 73 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   synchronization
353e0 2e 20 54 68 6f 75 67 68 20 74 68 65 79 20 61 72  . Though they ar
353f0 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69  e intended for i
35400 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
35410 79 20 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74  y SQLite, code t
35420 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
35430 74 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70  t SQLite is.** p
35440 65 72 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20  ermitted to use 
35450 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
35460 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
35470 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
35480 6f 64 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c  ode contains mul
35490 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
354a0 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73  tions.** of thes
354b0 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
354c0 2e 20 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74  .  An appropriat
354d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
354e0 0a 2a 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20  .** is selected 
354f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74  automatically at
35500 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20   compile-time.  
35510 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ^(The following.
35520 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
35530 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  ns are available
35540 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63   in the SQLite c
35550 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ore:.**.** <ul>.
35560 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
35570 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c  _MUTEX_OS2.** <l
35580 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
35590 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69  X_PTHREAD.** <li
355a0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
355b0 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  _W32.** <li>   S
355c0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
355d0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
355e0 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  * ^The SQLITE_MU
355f0 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
35600 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
35610 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20   of routines.** 
35620 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61  that does no rea
35630 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73  l locking and is
35640 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
35650 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e   use in.** a sin
35660 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70  gle-threaded app
35670 6c 69 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20  lication.  ^The 
35680 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32  SQLITE_MUTEX_OS2
35690 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  ,.** SQLITE_MUTE
356a0 58 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53  X_PTHREAD, and S
356b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20  QLITE_MUTEX_W32 
356c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
356d0 2a 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61  ** are appropria
356e0 74 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53  te for use on OS
356f0 2f 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69  /2, Unix, and Wi
35700 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ndows..**.** ^(I
35710 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
35720 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  iled with the SQ
35730 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
35740 46 20 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a  F preprocessor.*
35750 2a 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20  * macro defined 
35760 28 77 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f  (with "-DSQLITE_
35770 4d 55 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29  MUTEX_APPDEF=1")
35780 2c 20 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a  , then no mutex.
35790 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
357a0 6e 20 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69  n is included wi
357b0 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20  th the library. 
357c0 49 6e 20 74 68 69 73 20 63 61 73 65 20 74 68 65  In this case the
357d0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
357e0 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 63 75  must supply a cu
357f0 73 74 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65  stom mutex imple
35800 6d 65 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20  mentation using 
35810 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
35820 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74  ONFIG_MUTEX] opt
35830 69 6f 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ion of the sqlit
35840 65 33 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63  e3_config() func
35850 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63  tion.** before c
35860 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69  alling sqlite3_i
35870 6e 69 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61  nitialize() or a
35880 6e 79 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20  ny other public 
35890 73 71 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63  sqlite3_.** func
358a0 74 69 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20  tion that calls 
358b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
358c0 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ze().)^.**.** ^T
358d0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
358e0 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  _alloc() routine
358f0 20 61 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77   allocates a new
35900 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65  .** mutex and re
35910 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35920 74 6f 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65  to it. ^If it re
35930 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68  turns NULL.** th
35940 61 74 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  at means that a 
35950 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20  mutex could not 
35960 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e  be allocated.  ^
35970 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75  SQLite.** will u
35980 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20  nwind its stack 
35990 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72  and return an er
359a0 72 6f 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75  ror.  ^(The argu
359b0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
359c0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
359d0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   is one of these
359e0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
359f0 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ts:.**.** <ul>.*
35a00 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35a10 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69  UTEX_FAST.** <li
35a20 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
35a30 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69  RECURSIVE.** <li
35a40 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
35a50 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a  STATIC_MASTER.**
35a60 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
35a70 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a  TEX_STATIC_MEM.*
35a80 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35a90 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32  UTEX_STATIC_MEM2
35aa0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
35ab0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52  _MUTEX_STATIC_PR
35ac0 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  NG.** <li>  SQLI
35ad0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
35ae0 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  LRU.** <li>  SQL
35af0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
35b00 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _LRU2.** </ul>)^
35b10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
35b20 74 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  t two constants 
35b30 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41  (SQLITE_MUTEX_FA
35b40 53 54 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  ST and SQLITE_MU
35b50 54 45 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a  TEX_RECURSIVE).*
35b60 2a 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  * cause sqlite3_
35b70 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f  mutex_alloc() to
35b80 20 63 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77   create.** a new
35b90 20 6d 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65   mutex.  ^The ne
35ba0 77 20 6d 75 74 65 78 20 69 73 20 72 65 63 75 72  w mutex is recur
35bb0 73 69 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45  sive when SQLITE
35bc0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35bd0 0a 2a 2a 20 69 73 20 75 73 65 64 20 62 75 74 20  .** is used but 
35be0 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20  not necessarily 
35bf0 73 6f 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  so when SQLITE_M
35c00 55 54 45 58 5f 46 41 53 54 20 69 73 20 75 73 65  UTEX_FAST is use
35c10 64 2e 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  d..** The mutex 
35c20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64  implementation d
35c30 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
35c40 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69  make a distincti
35c50 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51  on.** between SQ
35c60 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
35c70 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  SIVE and SQLITE_
35c80 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69 74  MUTEX_FAST if it
35c90 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
35ca0 74 20 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77  t to.  ^SQLite w
35cb0 69 6c 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74  ill only request
35cc0 20 61 20 72 65 63 75 72 73 69 76 65 20 6d 75 74   a recursive mut
35cd0 65 78 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77  ex in.** cases w
35ce0 68 65 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e  here it really n
35cf0 65 65 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61  eeds one.  ^If a
35d00 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75   faster non-recu
35d10 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69  rsive mutex.** i
35d20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
35d30 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68   available on th
35d40 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c  e host platform,
35d50 20 74 68 65 20 6d 75 74 65 78 20 73 75 62 73 79   the mutex subsy
35d60 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65  stem.** might re
35d70 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65  turn such a mute
35d80 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f  x in response to
35d90 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
35da0 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  ST..**.** ^The o
35db0 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72  ther allowed par
35dc0 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74  ameters to sqlit
35dd0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
35de0 20 28 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72   (anything other
35df0 0a 2a 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f  .** than SQLITE_
35e00 4d 55 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53  MUTEX_FAST and S
35e10 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
35e20 52 53 49 56 45 29 20 65 61 63 68 20 72 65 74 75  RSIVE) each retu
35e30 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  rn.** a pointer 
35e40 74 6f 20 61 20 73 74 61 74 69 63 20 70 72 65 65  to a static pree
35e50 78 69 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20  xisting mutex.  
35e60 5e 53 69 78 20 73 74 61 74 69 63 20 6d 75 74 65  ^Six static mute
35e70 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20  xes are.** used 
35e80 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  by the current v
35e90 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
35ea0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
35eb0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
35ec0 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  may add addition
35ed0 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  al static mutexe
35ee0 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65 78  s.  Static mutex
35ef0 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72  es are for inter
35f00 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
35f10 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  Lite only.  Appl
35f20 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
35f30 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73  e SQLite mutexes
35f40 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f   should.** use o
35f50 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20  nly the dynamic 
35f60 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65 64  mutexes returned
35f70 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58   by SQLITE_MUTEX
35f80 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49  _FAST or.** SQLI
35f90 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
35fa0 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  VE..**.** ^Note 
35fb0 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74  that if one of t
35fc0 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  he dynamic mutex
35fd0 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c   parameters (SQL
35fe0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
35ff0 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45  * or SQLITE_MUTE
36000 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73 20  X_RECURSIVE) is 
36010 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65  used then sqlite
36020 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a  3_mutex_alloc().
36030 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69 66  ** returns a dif
36040 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20  ferent mutex on 
36050 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75  every call.  ^Bu
36060 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69 63  t for the static
36070 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c  .** mutex types,
36080 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20   the same mutex 
36090 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65  is returned on e
360a0 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68  very call that h
360b0 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  as.** the same t
360c0 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a  ype number..**.*
360d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
360e0 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74  utex_free() rout
360f0 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  ine deallocates 
36100 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20  a previously.** 
36110 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69  allocated dynami
36120 63 20 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74  c mutex.  ^SQLit
36130 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20  e is careful to 
36140 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79  deallocate every
36150 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  .** dynamic mute
36160 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61  x that it alloca
36170 74 65 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69  tes.  The dynami
36180 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e  c mutexes must n
36190 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20  ot be in.** use 
361a0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65  when they are de
361b0 61 6c 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65  allocated.  Atte
361c0 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f  mpting to deallo
361d0 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  cate a static.**
361e0 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69   mutex results i
361f0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
36200 76 69 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e  vior.  ^SQLite n
36210 65 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73  ever deallocates
36220 0a 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74  .** a static mut
36230 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ex..**.** ^The s
36240 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74  qlite3_mutex_ent
36250 65 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  er() and sqlite3
36260 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75  _mutex_try() rou
36270 74 69 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a  tines attempt.**
36280 20 74 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65   to enter a mute
36290 78 2e 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20  x.  ^If another 
362a0 74 68 72 65 61 64 20 69 73 20 61 6c 72 65 61 64  thread is alread
362b0 79 20 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74  y within the mut
362c0 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ex,.** sqlite3_m
362d0 75 74 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c  utex_enter() wil
362e0 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69  l block and sqli
362f0 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
36300 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53  will return.** S
36310 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68  QLITE_BUSY.  ^Th
36320 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  e sqlite3_mutex_
36330 74 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  try() interface 
36340 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
36350 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63  OK].** upon succ
36360 65 73 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e  essful entry.  ^
36370 28 4d 75 74 65 78 65 73 20 63 72 65 61 74 65 64  (Mutexes created
36380 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45   using.** SQLITE
36390 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
363a0 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20   can be entered 
363b0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62  multiple times b
363c0 79 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  y the same threa
363d0 64 2e 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61  d..** In such ca
363e0 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65  ses the,.** mute
363f0 78 20 6d 75 73 74 20 62 65 20 65 78 69 74 65 64  x must be exited
36400 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72   an equal number
36410 20 6f 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65   of times before
36420 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
36430 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20  ** can enter.)^ 
36440 20 5e 28 49 66 20 74 68 65 20 73 61 6d 65 20 74   ^(If the same t
36450 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65  hread tries to e
36460 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a  nter any other.*
36470 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20  * kind of mutex 
36480 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
36490 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
364a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51  undefined..** SQ
364b0 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
364c0 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20  exhibit.** such 
364d0 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20  behavior in its 
364e0 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78  own use of mutex
364f0 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f  es.)^.**.** ^(So
36500 6d 65 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20  me systems (for 
36510 65 78 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73  example, Windows
36520 20 39 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70   95) do not supp
36530 6f 72 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ort the operatio
36540 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64  n.** implemented
36550 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   by sqlite3_mute
36560 78 5f 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f  x_try().  On tho
36570 73 65 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69  se systems, sqli
36580 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a  te3_mutex_try().
36590 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  ** will always r
365a0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53  eturn SQLITE_BUS
365b0 59 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  Y.  The SQLite c
365c0 6f 72 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73  ore only ever us
365d0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75  es.** sqlite3_mu
365e0 74 65 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20  tex_try() as an 
365f0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20  optimization so 
36600 74 68 69 73 20 69 73 20 61 63 63 65 70 74 61 62  this is acceptab
36610 6c 65 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a  le behavior.)^.*
36620 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36630 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20  3_mutex_leave() 
36640 72 6f 75 74 69 6e 65 20 65 78 69 74 73 20 61 20  routine exits a 
36650 6d 75 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a  mutex that was.*
36660 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74  * previously ent
36670 65 72 65 64 20 62 79 20 74 68 65 20 73 61 6d 65  ered by the same
36680 20 74 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65   thread.   ^(The
36690 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
366a0 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74 68 65  undefined if the
366b0 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75   mutex is not cu
366c0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
366d0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e  by the.** callin
366e0 67 20 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e  g thread or is n
366f0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c  ot currently all
36700 6f 63 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20  ocated.  SQLite 
36710 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f  will.** never do
36720 20 65 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a   either.)^.**.**
36730 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e   ^If the argumen
36740 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  t to sqlite3_mut
36750 65 78 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69  ex_enter(), sqli
36760 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c  te3_mutex_try(),
36770 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   or.** sqlite3_m
36780 75 74 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20  utex_leave() is 
36790 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
367a0 74 68 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72  then all three r
367b0 6f 75 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76  outines.** behav
367c0 65 20 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  e as no-ops..**.
367d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
367e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
367f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36800 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
36810 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75  ]..*/.sqlite3_mu
36820 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74  tex *sqlite3_mut
36830 65 78 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  ex_alloc(int);.v
36840 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
36850 78 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d  x_free(sqlite3_m
36860 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  utex*);.void sql
36870 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
36880 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
36890 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  ;.int sqlite3_mu
368a0 74 65 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f  tex_try(sqlite3_
368b0 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71  mutex*);.void sq
368c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
368d0 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a  e(sqlite3_mutex*
368e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
368f0 45 46 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64  EF: Mutex Method
36900 73 20 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45  s Object.** EXPE
36910 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41  RIMENTAL.**.** A
36920 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
36930 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66  is structure def
36940 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76  ines the low-lev
36950 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75  el routines.** u
36960 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  sed to allocate 
36970 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e  and use mutexes.
36980 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20  .**.** Usually, 
36990 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
369a0 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
369b0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51  s provided by SQ
369c0 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66  Lite are.** suff
369d0 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20  icient, however 
369e0 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65  the user has the
369f0 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74   option of subst
36a00 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d  ituting a custom
36a10 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
36a20 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a  on for specializ
36a30 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f  ed deployments o
36a40 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68  r systems for wh
36a50 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f  ich SQLite.** do
36a60 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  es not provide a
36a70 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
36a80 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69  entation. In thi
36a90 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72  s case, the user
36aa0 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20  .** creates and 
36ab0 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73  populates an ins
36ac0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
36ad0 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a  ructure to pass.
36ae0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
36af0 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74  nfig() along wit
36b00 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  h the [SQLITE_CO
36b10 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69  NFIG_MUTEX] opti
36b20 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  on..** Additiona
36b30 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65  lly, an instance
36b40 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
36b50 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  re can be used a
36b60 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76  s an.** output v
36b70 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65  ariable when que
36b80 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d  rying the system
36b90 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
36ba0 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
36bb0 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20  entation, using 
36bc0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
36bd0 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74  IG_GETMUTEX] opt
36be0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
36bf0 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
36c00 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
36c10 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
36c20 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
36c30 74 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74  t of system init
36c40 69 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68  ialization by th
36c50 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
36c60 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e  lize() function.
36c70 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49  .** ^The xMutexI
36c80 6e 69 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63  nit routine is c
36c90 61 6c 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65  alle by SQLite e
36ca0 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20  xactly once for 
36cb0 65 61 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76  each.** effectiv
36cc0 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  e call to [sqlit
36cd0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
36ce0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75  ..**.** ^The xMu
36cf0 74 65 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65  texEnd method de
36d00 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
36d10 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
36d20 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
36d30 20 73 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e   system shutdown
36d40 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
36d50 73 68 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74  shutdown() funct
36d60 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c  ion. The.** impl
36d70 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
36d80 69 73 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70  is method is exp
36d90 65 63 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65  ected to release
36da0 20 61 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67   all outstanding
36db0 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62  .** resources ob
36dc0 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75  tained by the mu
36dd0 74 65 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c  tex methods impl
36de0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65  ementation, espe
36df0 63 69 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20  cially.** those 
36e00 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68 65 20  obtained by the 
36e10 78 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f  xMutexInit metho
36e20 64 2e 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45  d.  ^The xMutexE
36e30 6e 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  nd().** interfac
36e40 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61  e is invoked exa
36e50 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61  ctly once for ea
36e60 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
36e70 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
36e80 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d  .**.** ^(The rem
36e90 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74  aining seven met
36ea0 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20  hods defined by 
36eb0 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28  this structure (
36ec0 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20  xMutexAlloc,.** 
36ed0 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74  xMutexFree, xMut
36ee0 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54  exEnter, xMutexT
36ef0 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c  ry, xMutexLeave,
36f00 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a   xMutexHeld and.
36f10 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64  ** xMutexNotheld
36f20 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  ) implement the 
36f30 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66  following interf
36f40 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65  aces (respective
36f50 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ly):.**.** <ul>.
36f60 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
36f70 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
36f80 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
36f90 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
36fa0 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e  ex_free()] </li>
36fb0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
36fc0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
36fd0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
36fe0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
36ff0 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e  tex_try()] </li>
37000 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
37010 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
37020 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
37030 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
37040 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69  tex_held()] </li
37050 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
37060 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
37070 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  eld()] </li>.** 
37080 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
37090 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
370a0 65 20 69 73 20 74 68 61 74 20 74 68 65 20 70 75  e is that the pu
370b0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58  blic sqlite3_XXX
370c0 20 66 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65   functions enume
370d0 72 61 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73  rated.** above s
370e0 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61  ilently ignore a
370f0 6e 79 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74  ny invocations t
37100 68 61 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20  hat pass a NULL 
37110 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a  pointer instead.
37120 2a 2a 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75  ** of a valid mu
37130 74 65 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20  tex handle. The 
37140 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37150 6f 66 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64  of the methods d
37160 65 66 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69  efined.** by thi
37170 73 20 73 74 72 75 63 74 75 72 65 20 61 72 65 20  s structure are 
37180 6e 6f 74 20 72 65 71 75 69 72 65 64 20 74 6f 20  not required to 
37190 68 61 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65  handle this case
371a0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a  , the results.**
371b0 20 6f 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55   of passing a NU
371c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  LL pointer inste
371d0 61 64 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75  ad of a valid mu
371e0 74 65 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75  tex handle are u
371f0 6e 64 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65  ndefined.** (i.e
37200 2e 20 69 74 20 69 73 20 61 63 63 65 70 74 61 62  . it is acceptab
37210 6c 65 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e  le to provide an
37220 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37230 74 68 61 74 20 73 65 67 66 61 75 6c 74 73 20 69  that segfaults i
37240 66 0a 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65  f.** it is passe
37250 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
37260 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75  )..**.** The xMu
37270 74 65 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64  texInit() method
37280 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
37290 61 66 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62  afe.  ^It must b
372a0 65 20 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a  e harmless to.**
372b0 20 69 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e   invoke xMutexIn
372c0 69 74 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d  it() mutiple tim
372d0 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
372e0 6d 65 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77  me process and w
372f0 69 74 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76  ithout.** interv
37300 65 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78  ening calls to x
37310 4d 75 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63  MutexEnd().  Sec
37320 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
37330 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78  nt calls to.** x
37340 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74  MutexInit() must
37350 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
37360 2a 20 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20  * ^xMutexInit() 
37370 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c  must not use SQL
37380 69 74 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ite memory alloc
37390 61 74 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f  ation ([sqlite3_
373a0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64  malloc()].** and
373b0 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 73 29   its associates)
373c0 2e 20 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78  .  ^Similarly, x
373d0 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73  MutexAlloc() mus
373e0 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65  t not use SQLite
373f0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
37400 61 74 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74  ation for a stat
37410 69 63 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65  ic mutex.  ^Howe
37420 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28  ver xMutexAlloc(
37430 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65  ) may use SQLite
37440 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
37450 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74  ation for a fast
37460 20 6f 72 20 72 65 63 75 72 73 69 76 65 20 6d 75   or recursive mu
37470 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  tex..**.** ^SQLi
37480 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
37490 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d  he xMutexEnd() m
374a0 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69  ethod when [sqli
374b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
374c0 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75  is.** called, bu
374d0 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72  t only if the pr
374e0 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74  ior call to xMut
374f0 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20  exInit returned 
37500 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66  SQLITE_OK..** If
37510 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c   xMutexInit fail
37520 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74  s in any way, it
37530 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f 20   is expected to 
37540 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20 69  clean up after i
37550 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74  tself.** prior t
37560 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a  o returning..*/.
37570 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
37580 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
37590 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74  hods sqlite3_mut
375a0 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  ex_methods;.stru
375b0 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
375c0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74  _methods {.  int
375d0 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76   (*xMutexInit)(v
375e0 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  oid);.  int (*xM
375f0 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a  utexEnd)(void);.
37600 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20    sqlite3_mutex 
37610 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28  *(*xMutexAlloc)(
37620 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  int);.  void (*x
37630 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69 74  MutexFree)(sqlit
37640 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76  e3_mutex *);.  v
37650 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65  oid (*xMutexEnte
37660 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  r)(sqlite3_mutex
37670 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75   *);.  int (*xMu
37680 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f  texTry)(sqlite3_
37690 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64  mutex *);.  void
376a0 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28   (*xMutexLeave)(
376b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
376c0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
376d0 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75  Held)(sqlite3_mu
376e0 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  tex *);.  int (*
376f0 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73  xMutexNotheld)(s
37700 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
37710 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
37720 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66  REF: Mutex Verif
37730 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ication Routines
37740 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37750 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
37760 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  and sqlite3_mute
37770 78 5f 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74  x_notheld() rout
37780 69 6e 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65  ines.** are inte
37790 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  nded for use ins
377a0 69 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ide assert() sta
377b0 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53  tements.  ^The S
377c0 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65  QLite core.** ne
377d0 76 65 72 20 75 73 65 73 20 74 68 65 73 65 20 72  ver uses these r
377e0 6f 75 74 69 6e 65 73 20 65 78 63 65 70 74 20 69  outines except i
377f0 6e 73 69 64 65 20 61 6e 20 61 73 73 65 72 74 28  nside an assert(
37800 29 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f  ) and applicatio
37810 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65  ns.** are advise
37820 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20  d to follow the 
37830 6c 65 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65  lead of the core
37840 2e 20 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63  .  ^The SQLite c
37850 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76  ore only.** prov
37860 69 64 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ides implementat
37870 69 6f 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72  ions for these r
37880 6f 75 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20  outines when it 
37890 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
378a0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ith the SQLITE_D
378b0 45 42 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74  EBUG flag.  ^Ext
378c0 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c  ernal mutex impl
378d0 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
378e0 72 65 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64  re only required
378f0 20 74 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73   to provide thes
37900 65 20 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51  e routines if SQ
37910 4c 49 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a  LITE_DEBUG is.**
37920 20 64 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20   defined and if 
37930 4e 44 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65  NDEBUG is not de
37940 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
37950 65 73 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  ese routines sho
37960 75 6c 64 20 72 65 74 75 72 6e 20 74 72 75 65 20  uld return true 
37970 69 66 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20  if the mutex in 
37980 74 68 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a  their argument.*
37990 2a 20 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74  * is held or not
379a0 20 68 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76   held, respectiv
379b0 65 6c 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c  ely, by the call
379c0 69 6e 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  ing thread..**.*
379d0 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  * ^The implement
379e0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71  ation is not req
379f0 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65  uired to provide
37a00 64 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  d versions of th
37a10 65 73 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ese.** routines 
37a20 74 68 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f  that actually wo
37a30 72 6b 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65  rk. If the imple
37a40 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e  mentation does n
37a50 6f 74 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69  ot provide worki
37a60 6e 67 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  ng.** versions o
37a70 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
37a80 2c 20 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c  , it should at l
37a90 65 61 73 74 20 70 72 6f 76 69 64 65 20 73 74 75  east provide stu
37aa0 62 73 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a  bs that always.*
37ab0 2a 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f  * return true so
37ac0 20 74 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e   that one does n
37ad0 6f 74 20 67 65 74 20 73 70 75 72 69 6f 75 73 20  ot get spurious 
37ae0 61 73 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72  assertion failur
37af0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
37b00 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  e argument to sq
37b10 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
37b20 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
37b30 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65  nter then.** the
37b40 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20   routine should 
37b50 72 65 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73  return 1.   This
37b60 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69   seems counter-i
37b70 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a  ntuitive since.*
37b80 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75  * clearly the mu
37b90 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65  tex cannot be he
37ba0 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f  ld if it does no
37bb0 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74 68  t exist.  But th
37bc0 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20  e.** the reason 
37bd0 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e  the mutex does n
37be0 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63 61  ot exist is beca
37bf0 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69 73  use the build is
37c00 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75   not.** using mu
37c10 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64  texes.  And we d
37c20 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61  o not want the a
37c30 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69  ssert() containi
37c40 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74  ng the.** call t
37c50 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
37c60 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20  held() to fail, 
37c70 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  so a non-zero re
37c80 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61  turn is.** the a
37c90 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67  ppropriate thing
37ca0 20 74 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71   to do.  ^The sq
37cb0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
37cc0 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  eld().** interfa
37cd0 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72  ce should also r
37ce0 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76  eturn 1 when giv
37cf0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
37d00 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44  r..*/.#ifndef ND
37d10 45 42 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33  EBUG.int sqlite3
37d20 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69  _mutex_held(sqli
37d30 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74  te3_mutex*);.int
37d40 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
37d50 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d  otheld(sqlite3_m
37d60 75 74 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a  utex*);.#endif..
37d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37d80 4d 75 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a  Mutex Types.**.*
37d90 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
37da0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e  utex_alloc()] in
37db0 74 65 72 66 61 63 65 20 74 61 6b 65 73 20 61 20  terface takes a 
37dc0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a  single argument.
37dd0 2a 2a 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20  ** which is one 
37de0 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
37df0 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
37e00 2a 20 54 68 65 20 73 65 74 20 6f 66 20 73 74 61  * The set of sta
37e10 74 69 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20  tic mutexes may 
37e20 63 68 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20  change from one 
37e30 53 51 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74  SQLite release t
37e40 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
37e50 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
37e60 74 20 6f 76 65 72 72 69 64 65 20 74 68 65 20 62  t override the b
37e70 75 69 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f  uilt-in mutex lo
37e80 67 69 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70  gic must be.** p
37e90 72 65 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d  repared to accom
37ea0 6d 6f 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61  modate additiona
37eb0 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  l static mutexes
37ec0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
37ed0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20  ITE_MUTEX_FAST  
37ee0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
37ef0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37f00 58 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  X_RECURSIVE     
37f10 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
37f20 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37f30 5f 4d 41 53 54 45 52 20 20 20 20 32 0a 23 64 65  _MASTER    2.#de
37f40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37f50 58 5f 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20  X_STATIC_MEM    
37f60 20 20 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33     3  /* sqlite3
37f70 5f 6d 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65  _malloc() */.#de
37f80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  fine SQLITE_MUTE
37f90 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20  X_STATIC_MEM2   
37fa0 20 20 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45     4  /* NOT USE
37fb0 44 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  D */.#define SQL
37fc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37fd0 5f 4f 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a  _OPEN      4  /*
37fe0 20 73 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65   sqlite3BtreeOpe
37ff0 6e 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  n() */.#define S
38000 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
38010 49 43 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20  IC_PRNG      5  
38020 2f 2a 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  /* sqlite3_rando
38030 6d 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  m() */.#define S
38040 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
38050 49 43 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20  IC_LRU       6  
38060 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74  /* lru page list
38070 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
38080 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
38090 4c 52 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20  LRU2      7  /* 
380a0 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f  lru page list */
380b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
380c0 3a 20 52 65 74 72 69 65 76 65 20 74 68 65 20 6d  : Retrieve the m
380d0 75 74 65 78 20 66 6f 72 20 61 20 64 61 74 61 62  utex for a datab
380e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
380f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
38100 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
38110 6f 69 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69  ointer the [sqli
38120 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
38130 74 20 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61  t that .** seria
38140 6c 69 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20  lizes access to 
38150 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38160 6e 6e 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20  nnection] given 
38170 69 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a  in the argument.
38180 2a 2a 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72  ** when the [thr
38190 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
381a0 53 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e  Serialized..** ^
381b0 49 66 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  If the [threadin
381c0 67 20 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c  g mode] is Singl
381d0 65 2d 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74  e-thread or Mult
381e0 69 2d 74 68 72 65 61 64 20 74 68 65 6e 20 74 68  i-thread then th
381f0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  is.** routine re
38200 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
38210 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  nter..*/.sqlite3
38220 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f  _mutex *sqlite3_
38230 64 62 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33  db_mutex(sqlite3
38240 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
38250 52 45 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43  REF: Low-Level C
38260 6f 6e 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61  ontrol Of Databa
38270 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
38280 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  The [sqlite3_fil
38290 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
382a0 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64  erface makes a d
382b0 69 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68  irect call to th
382c0 65 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f  e.** xFileContro
382d0 6c 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65  l method for the
382e0 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
382f0 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73  hods] object ass
38300 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
38310 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74  a particular dat
38320 61 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64  abase identified
38330 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
38340 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a  rgument. ^The.**
38350 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
38360 61 62 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72  abase "main" for
38370 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
38380 73 65 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72  se or "temp" for
38390 20 74 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74   the.** TEMP dat
383a0 61 62 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61  abase, or the na
383b0 6d 65 20 74 68 61 74 20 61 70 70 65 61 72 73 20  me that appears 
383c0 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79  after the AS key
383d0 77 6f 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61  word for.** data
383e0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 61  bases that are a
383f0 64 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  dded using the [
38400 41 54 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d  ATTACH] SQL comm
38410 61 6e 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20  and..** ^A NULL 
38420 70 6f 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75  pointer can be u
38430 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  sed in place of 
38440 22 6d 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20  "main" to refer 
38450 74 6f 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64  to the.** main d
38460 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
38470 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
38480 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
38490 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  s to this routin
384a0 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20  e.** are passed 
384b0 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68  directly through
384c0 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61   to the second a
384d0 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  nd third paramet
384e0 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46  ers of.** the xF
384f0 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
38500 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20  d.  ^The return 
38510 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69  value of the xFi
38520 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74  leControl.** met
38530 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  hod becomes the 
38540 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
38550 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
38560 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f  .** ^If the seco
38570 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44  nd parameter (zD
38580 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20  bName) does not 
38590 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f  match the name o
385a0 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61  f any.** open da
385b0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
385c0 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69  n SQLITE_ERROR i
385d0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
385e0 69 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  is error.** code
385f0 20 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72   is not remember
38600 65 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20  ed and will not 
38610 62 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b  be recalled by [
38620 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
38630 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
38640 33 5f 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68  3_errmsg()].  Th
38650 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69  e underlying xFi
38660 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
38670 20 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72   might.** also r
38680 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52  eturn SQLITE_ERR
38690 4f 52 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f  OR.  There is no
386a0 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75   way to distingu
386b0 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61  ish between.** a
386c0 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e  n incorrect zDbN
386d0 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54  ame and an SQLIT
386e0 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66  E_ERROR return f
386f0 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69  rom the underlyi
38700 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  ng.** xFileContr
38710 6f 6c 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a  ol method..**.**
38720 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
38730 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
38740 54 45 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  TE].*/.int sqlit
38750 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
38760 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
38770 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69  char *zDbName, i
38780 6e 74 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt op, void*);..
38790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
387a0 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63  Testing Interfac
387b0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
387c0 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
387d0 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  l() interface is
387e0 20 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75   used to read ou
387f0 74 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74  t internal.** st
38800 61 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e  ate of SQLite an
38810 64 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c  d to inject faul
38820 74 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66  ts into SQLite f
38830 6f 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75  or testing.** pu
38840 72 70 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69  rposes.  ^The fi
38850 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
38860 20 61 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f   an operation co
38870 64 65 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  de that determin
38880 65 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  es.** the number
38890 2c 20 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f  , meaning, and o
388a0 70 65 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20  peration of all 
388b0 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
388c0 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  eters..**.** Thi
388d0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
3